Skip to content

feat: add type-safe preferences system with AsyncContext#5

Merged
Gaubee merged 1 commit intomainfrom
feat/preferences-system
Dec 19, 2025
Merged

feat: add type-safe preferences system with AsyncContext#5
Gaubee merged 1 commit intomainfrom
feat/preferences-system

Conversation

@Gaubee
Copy link
Copy Markdown
Collaborator

@Gaubee Gaubee commented Dec 19, 2025

Summary

Add a comprehensive type-safe preferences configuration system with AsyncContext integration.

Key Features

1. Preferences Builder API

definePreferences((ctx, p) =>
  p
    .ai((ai) => ai
      .profile("claude-code", (p) => p.useClaudeCodeAgentSdk({
        permissionMode: ctx.env.isDev ? "acceptEdits" : "default",
      }))
      .profile("codex", (p) => p.useCodexAgent({
        modelReasoningEffort: "high",
      }))
    )
    .workflow("git-committer", (w) => w.preferredAgent("codex"))
    .build()
);

2. AsyncContext Integration

  • Workflow handlers automatically run within PreferencesContext
  • Access preferences anywhere in the call chain without parameter passing
  • Uses Node.js AsyncLocalStorage for async context propagation

3. SDK Type Integration

  • Direct types from @anthropic-ai/claude-agent-sdk and @openai/codex-sdk
  • Type-safe profile configuration

4. Whitebook as Prompt Source

  • Read documentation as AI prompts (single source of truth)
  • loadWhitebookAsPrompt() utility

Files Changed

File Description
common/preferences.builder.ts Fluent builder API
common/preferences.schema.ts Zod schema definitions
common/async-context.ts AsyncLocalStorage wrapper
common/whitebook.ts Whitebook reading utilities
workflows/shared/base-workflow.ts AsyncContext integration
meta/subflows/preferences.workflow.ts Renamed from config.workflow.ts
docs/white-book/06-configuration/preferences-api.md API documentation

Tests

  • 89 tests total (all passing)
  • Unit tests for builder, schema, async-context, whitebook
  • Integration tests for workflow + AsyncContext

- Add preferences.builder.ts with fluent API for configuration
- Add preferences.schema.ts with Zod validation
- Add async-context.ts with AsyncLocalStorage-based context
- Integrate AsyncContext into base-workflow.ts automatically
- Rename config.workflow.ts to preferences.workflow.ts
- Add whitebook.ts for reading docs as AI prompts
- Add preferences-api.md documentation
- Add comprehensive test suites (89 tests total)

Key features:
- Type-safe builder: definePreferences((ctx, p) => ...)
- SDK types from @anthropic-ai/claude-agent-sdk and @openai/codex-sdk
- Profile-based configuration with builtin claude-code and codex
- AsyncContext for non-invasive preference access across call chain
- Workflow handlers automatically run within PreferencesContext
@Gaubee Gaubee merged commit 4b5d69c into main Dec 19, 2025
3 checks passed
@Gaubee Gaubee deleted the feat/preferences-system branch December 19, 2025 12:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant