@keystrokehq/skills 0.0.1

package/keystroke-agent-authoring/references/messaging-gateways.md

@@ -0,0 +1,242 @@
+# Messaging Gateway Patterns
+
+Read this file when the user wants a Keystroke agent to be entered through Slack, GitHub, or Linear conversations.
+
+## What a gateway is
+
+Use `MessagingGateway` on `Agent.messaging` when the agent should receive and continue conversations through a messaging surface.
+
+File layout reminder:
+- keep each exported gateway in its own `*.gateway.ts` file
+- keep the agent in its own `*.agent.ts` file
+- keep the gateway credential set in its own `*.credential-set.ts` file
+
+Teach this vocabulary clearly:
+- a messaging gateway is a conversation entrypoint for an agent
+- a messaging gateway is not a workflow trigger
+- a messaging gateway is not a task
+- workflows and tasks can still call agents, but conversational entry belongs on the agent
+
+## Core fields
+
+- `id`
+- `name`
+- `description`
+- `provider`
+- `mode`
+- `credentialSet`
+- `credentialScope`
+- `appRef`
+
+## Platform gateway (default)
+
+Use this when the user wants messaging through the Keystroke-managed app. This is the default unless the user says otherwise.
+
+```ts
+import { CredentialSet, MessagingGateway } from '@keystrokehq/core';
+import { z } from 'zod';
+
+export const slackGatewayCredentials = new CredentialSet({
+  id: 'slackGateway',
+  auth: z.object({
+    SLACK_BOT_TOKEN: z.string(),
+  }),
+});
+
+export const supportSlackGateway = new MessagingGateway({
+  id: 'support-slack',
+  name: 'Support Slack Gateway',
+  provider: 'slack',
+  mode: 'platform',
+  credentialSet: slackGatewayCredentials,
+  credentialScope: 'organization',
+});
+```
+
+## Custom app gateway
+
+Use this only when the user explicitly wants to use their own app or create a new app with a specific name.
+
+```ts
+import { CredentialSet, MessagingGateway } from '@keystrokehq/core';
+import { z } from 'zod';
+
+export const customSlackCredentials = new CredentialSet({
+  id: 'slackCustom',
+  auth: z.object({
+    botToken: z.string(),
+    signingSecret: z.string(),
+  }),
+});
+
+export const customSlackGateway = new MessagingGateway({
+  id: 'sales-slack',
+  name: 'Sales Slack Gateway',
+  provider: 'slack',
+  mode: 'custom',
+  credentialSet: customSlackCredentials,
+  credentialScope: 'organization',
+  appRef: 'sales-bot',
+});
+```
+
+Key differences from the platform gateway:
+- `mode` is `'custom'` instead of `'platform'`
+- `appRef` identifies which user-created app this gateway connects to
+- the credential set typically requires more fields because the user supplies all auth values
+
+## Prebuilt gateway helpers from `@keystroke/integration-slack`
+
+Integration packages ship prebuilt gateway factories so users don't need to wire credential sets manually. Prefer these over hand-constructing a `MessagingGateway` with `@keystrokehq/core` when the provider has one available.
+
+### Platform gateway (prebuilt)
+
+```ts
+import { slackPlatformGateway } from '@keystroke/integration-slack/platform';
+
+export const supportGateway = slackPlatformGateway();
+```
+
+`slackPlatformGateway()` returns a `mode: 'platform'` gateway with the Keystroke-managed Slack installation credentials already configured. Override `id`, `name`, or `description` when needed:
+
+```ts
+export const supportGateway = slackPlatformGateway({
+  id: 'support-slack',
+  name: 'Support Slack Gateway',
+  description: 'Handles support conversations in Slack.',
+});
+```
+
+### Custom app gateway (prebuilt)
+
+```ts
+import { slackCustomGateway } from '@keystroke/integration-slack/custom';
+
+export const salesGateway = slackCustomGateway({
+  appRef: 'sales-bot',
+});
+```
+
+`slackCustomGateway()` returns a `mode: 'custom'` gateway using the user-provided Slack app credentials. `appRef` identifies which custom app installation to route through. Override `id`, `name`, or `description` when needed:
+
+```ts
+export const salesGateway = slackCustomGateway({
+  appRef: 'sales-bot',
+  id: 'sales-slack',
+  name: 'Sales Slack Gateway',
+});
+```
+
+### When to use prebuilt vs manual
+
+- Use the prebuilt helpers when the provider integration package exports them — they already bundle the correct credential sets and mode.
+- Fall back to manual `new MessagingGateway({...})` when no prebuilt helper exists for the provider, or when the credential set needs to differ from the integration default.
+
+## Agent with messaging
+
+Using a prebuilt gateway:
+
+```ts
+import { anthropic } from '@keystroke/integration-ai';
+import { Agent } from '@keystrokehq/core';
+import { slackPlatformGateway } from '@keystroke/integration-slack/platform';
+
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'Support Agent',
+  systemPrompt: 'Answer support requests and use tools when needed.',
+  model: 'anthropic/claude-sonnet-4-20250514',
+  credentialSets: [anthropic],
+  messaging: [slackPlatformGateway()],
+});
+```
+
+Or importing a gateway from its own file:
+
+```ts
+import { anthropic } from '@keystroke/integration-ai';
+import { Agent } from '@keystrokehq/core';
+import { supportSlackGateway } from './support-slack.gateway';
+
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'Support Agent',
+  systemPrompt: 'Answer support requests and use tools when needed.',
+  model: 'anthropic/claude-sonnet-4-20250514',
+  credentialSets: [anthropic],
+  messaging: [supportSlackGateway],
+});
+```
+
+## `provider`
+
+Current provider values in `core` are:
+- `slack`
+- `linear`
+- `github`
+
+Choose the provider that matches the conversation surface the user wants.
+
+## `mode` — platform app vs custom app
+
+There are two kinds of messaging app a gateway can use. Teach this distinction clearly:
+
+### Platform app (`mode: 'platform'`)
+
+A **platform app** is a Keystroke-owned and Keystroke-managed app (e.g. a Slack bot, GitHub App, or Linear integration) that the user **installs** into their workspace, organization, or repo. The user does not create or configure this app themselves — Keystroke provides it and handles the OAuth installation flow.
+
+- **This is the default.** When the user asks for a messaging gateway without specifying that they want to create their own app or use a differently-named app, use `mode: 'platform'`.
+- Platform gateways do not need `appRef` because the platform already knows which app to use.
+- Credentials are resolved through the platform's installation flow, not manually provided by the user.
+
+### Custom app (`mode: 'custom'`)
+
+A **custom app** is an app that the user **creates on their own** in the provider's developer portal (e.g. a custom Slack app, a self-managed GitHub App). The user provides their own credentials (bot tokens, signing secrets, app IDs, private keys, etc.).
+
+- Use `mode: 'custom'` only when the user explicitly says they want to create their own app, use their own app, or reference a specific app name that is not the Keystroke platform app.
+- Custom gateways typically include `appRef` to identify which custom app installation to route through.
+- The credential set for a custom gateway usually requires more fields than a platform gateway because the user must supply all auth values directly.
+
+### Choosing the right mode
+
+| Signal from the user | Mode |
+|---|---|
+| "connect Slack" / "add Slack messaging" / no app preference stated | `platform` |
+| "I already have a Slack app" / "use my own app" | `custom` |
+| "create a Slack app called support-bot" | `custom` with `appRef` |
+| "use the Keystroke Slack app" | `platform` |
+
+When in doubt, default to `platform`.
+
+## `credentialScope`
+
+Use credential scope when the gateway credentials should resolve at:
+- `organization`
+- `project`
+
+This is a gateway-specific authoring concern and should be cross-linked with the credential skill.
+
+## `appRef`
+
+Use `appRef` only with `mode: 'custom'` to identify which user-created app installation the gateway routes through.
+
+- Platform gateways should not set `appRef` — the platform knows which app to use.
+- Custom gateways should set `appRef` to a stable name that identifies the user's app (e.g. `'support-bot'`, `'sales-bot'`).
+
+## Prebuilt helpers by provider
+
+Integration packages and `core` export gateway factory functions so users don't need to construct gateways manually:
+
+- **Slack**: `slackPlatformGateway()` from `@keystroke/integration-slack/platform`, `slackCustomGateway()` from `@keystroke/integration-slack/custom`
+- **GitHub**: `githubPlatformGateway()` from `@keystrokehq/core`
+
+Use these when the helper fits. Fall back to `new MessagingGateway({...})` when no helper exists for the provider or the credential set needs to differ.
+
+## Gotchas
+
+- Default to `mode: 'platform'` unless the user explicitly asks to use their own app or create a custom app.
+- Do not use `appRef` on platform gateways.
+- Do not explain a messaging gateway as a workflow trigger.
+- Do not attach a messaging gateway to a workflow.
+- Do not put gateway setup in the system prompt.
+- Keep credentials on the gateway or related credential set, not in `process.env` inside authored code.

package/keystroke-agent-authoring/references/patterns.md

@@ -0,0 +1,417 @@
+# Agent And Tool / Operation Examples
+
+Use these examples when the user needs concrete patterns for public agent APIs.
+
+`Operation`, `Step`, and `Tool` are aliases for the same class. In this agent reference, examples default to `Tool` because that name reads best from agent context.
+
+Some later snippets reuse symbols from earlier snippets in this file, such as `crmCredentials` or `deleteRecordTool`.
+
+File layout reminder:
+
+- keep every exported primitive in its own typed file
+- `*.agent.ts` exports one agent
+- `*.tool.ts`, `*.step.ts`, or `*.operation.ts` exports one operation
+- `*.credential-set.ts`, `*.sandbox.ts`, and `*.mcp-server.ts` each export one primitive
+- when a snippet reuses `crmCredentials`, `lookupCustomerTool`, or another primitive, import it from its own typed file
+
+## Minimal `Agent`
+
+```ts
+import { anthropic } from '@keystroke/integration-ai';
+import { Agent } from '@keystrokehq/core';
+
+export const summarizer = new Agent({
+  id: 'summarizer',
+  name: 'Summarizer',
+  systemPrompt: 'Summarize the input in one paragraph.',
+  model: 'anthropic/claude-sonnet-4-20250514',
+  credentialSets: [anthropic],
+});
+```
+
+This is the smallest runnable authored agent:
+
+- `id` identifies the agent
+- `systemPrompt` tells the model how to behave
+- `model` selects the model
+
+## `Agent` with optional fields
+
+```ts
+import { anthropic } from '@keystroke/integration-ai';
+import { Agent, CredentialSet } from '@keystrokehq/core';
+import { z } from 'zod';
+
+const searchCredentials = new CredentialSet({
+  id: 'searchApi',
+  name: 'Search API',
+  auth: z.object({
+    apiKey: z.string(),
+  }),
+});
+
+export const researchAgent = new Agent({
+  id: 'research-agent',
+  name: 'Research Agent',
+  description: 'Finds information and writes a short summary.',
+  systemPrompt: 'Search first. Summarize second. Cite the key facts you found.',
+  model: 'anthropic/claude-sonnet-4-20250514',
+  credentialSets: [anthropic, searchCredentials],
+  maxSteps: 12,
+});
+```
+
+Use this shape when the agent needs metadata, credentials, or a larger step budget.
+
+## Custom `Tool`
+
+```ts
+import { Tool } from '@keystrokehq/core';
+import { z } from 'zod';
+
+export const formatTicketTool = new Tool({
+  id: 'format_ticket',
+  name: 'Format Ticket',
+  description: 'Formats a support ticket for downstream systems.',
+  input: z.object({
+    title: z.string(),
+    priority: z.enum(['low', 'medium', 'high']),
+  }),
+  output: z.object({
+    text: z.string(),
+  }),
+  run: (input) => {
+    return {
+      text: `[${input.priority.toUpperCase()}] ${input.title}`,
+    };
+  },
+});
+```
+
+The same example could also be written with `new Operation({...})` if the unit is shared outside agent code.
+
+## Workflow Tool
+
+```ts
+import { anthropic } from '@keystroke/integration-ai';
+import { Agent, Workflow } from '@keystrokehq/core';
+import { z } from 'zod';
+import { lookupCustomerTool } from './lookup-customer.tool';
+
+export const auditAccountWorkflow = new Workflow({
+  id: 'audit-account',
+  name: 'Audit Account',
+  description: 'Collects customer facts and returns audit findings.',
+  largeResultMode: 'ref',
+  input: z.object({
+    accountId: z.string(),
+  }),
+  output: z.object({
+    findings: z.array(z.string()),
+  }),
+  run: async () => ({
+    findings: [],
+  }),
+});
+
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'Support Agent',
+  systemPrompt: 'Use account data before answering account-specific questions.',
+  model: 'anthropic/claude-sonnet-4-20250514',
+  credentialSets: [anthropic],
+  tools: [lookupCustomerTool, auditAccountWorkflow],
+});
+```
+
+Workflow tools are enriched at build time. Sync workflows return direct results. Suspending workflows yield and resume later; hook workflows use `provide_workflow_response`, and large outputs can become refs inspected with `describe_ref`, `read_ref`, and `slice_ref`.
+
+Use `midSessionSnapshot: true` on the workflow only when measured workloads benefit from Phase D snapshot replay. The default yield path is simpler and usually preferred.
+
+## `Tool` with `needsApproval`
+
+```ts
+import { Tool } from '@keystrokehq/core';
+import { z } from 'zod';
+
+const deleteRecordTool = new Tool({
+  id: 'delete_record',
+  name: 'Delete Record',
+  description: 'Deletes a record from the remote system.',
+  needsApproval: true,
+  input: z.object({
+    recordId: z.string(),
+  }),
+  output: z.object({
+    deleted: z.boolean(),
+  }),
+  run: async () => ({ deleted: true }),
+});
+```
+
+## `Tool` with `credentialSets` and `workflowGlobals`
+
+```ts
+import { CredentialSet, Tool } from '@keystrokehq/core';
+import { z } from 'zod';
+
+const crmCredentials = new CredentialSet({
+  id: 'crmApi',
+  name: 'CRM API',
+  auth: z.object({
+    apiKey: z.string(),
+  }),
+});
+
+const lookupCustomerTool = new Tool({
+  id: 'lookup_customer',
+  name: 'Lookup Customer',
+  description: 'Loads a customer for the current tenant.',
+  credentialSets: [crmCredentials],
+  workflowGlobals: z.object({
+    tenantId: z.string(),
+  }),
+  input: z.object({
+    customerId: z.string(),
+  }),
+  output: z.object({
+    keyUsed: z.string(),
+    tenantId: z.string(),
+  }),
+  run: async (_input, ctx) => {
+    return {
+      keyUsed: ctx.credentials.crmApi.apiKey,
+      tenantId: ctx.workflowGlobals.tenantId,
+    };
+  },
+});
+```
+
+Use this when the tool depends on both credentials and workflow-provided runtime values.
+
+## Runnable `Agent`
+
+```ts
+import { Agent, Tool } from '@keystrokehq/core';
+import { z } from 'zod';
+
+const echoTool = new Tool({
+  id: 'echo',
+  name: 'Echo',
+  description: 'Returns the same text.',
+  input: z.object({ text: z.string() }),
+  output: z.object({ text: z.string() }),
+  run: (input) => ({ text: input.text }),
+});
+
+export const rawAgent = new Agent({
+  id: 'raw-agent',
+  name: 'Raw Agent',
+  description: 'Example low-level agent.',
+  systemPrompt: 'Use the tool output when it helps.',
+  model: 'anthropic/claude-sonnet-4-20250514',
+  input: z.object({
+    text: z.string(),
+  }),
+  output: z.object({
+    ok: z.boolean(),
+  }),
+  tools: [echoTool],
+  maxSteps: 5,
+  run: async () => {
+    return {
+      output: { ok: true },
+      session: {
+        id: 'session_123',
+        agentId: 'raw-agent',
+        messages: [],
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      },
+      steps: 1,
+      toolCalls: [],
+    };
+  },
+});
+```
+
+This form is useful when:
+
+- the agent needs explicit `input` and `output` schemas
+- the agent should provide its own custom `run(...)`
+- the agent should provide its own custom `stream(...)`
+
+## `agent.run(...)`
+
+```ts
+const result = await researchAgent.run('Research the account and summarize the findings.');
+```
+
+Use `run(...)` when the caller wants the final agent result.
+
+## `agent.stream(...)`
+
+```ts
+for await (const event of researchAgent.stream('Research the account and summarize the findings.')) {
+  // Handle streamed event.type here.
+}
+```
+
+Use `stream(...)` when the caller wants incremental events such as:
+
+- text
+- tool calls
+- tool results
+- completion
+
+## Agent hooks
+
+```ts
+import { anthropic } from '@keystroke/integration-ai';
+import { Agent } from '@keystrokehq/core';
+
+export const guardedAgent = new Agent({
+  id: 'guarded-agent',
+  name: 'Guarded Agent',
+  systemPrompt: 'Never call destructive tools without approval.',
+  model: 'anthropic/claude-sonnet-4-20250514',
+  credentialSets: [anthropic],
+  hooks: {
+    onToolStart: async (tool, input) => {
+      if (tool === 'delete_record') {
+        return {
+          allow: false,
+          replacement: {
+            blocked: true,
+            originalInput: input,
+          },
+        };
+      }
+
+      return { allow: true };
+    },
+    onToolEnd: async (tool, result) => {
+      // Observe the completed tool result here.
+    },
+    onStep: async (step) => {
+      // Observe each agent step here.
+    },
+  },
+});
+```
+
+Hook usage:
+
+- `onToolStart`: inspect or block a tool call before it runs
+- `onToolEnd`: observe the tool result after it runs
+- `onStep`: observe each model/tool step
+
+## `Tool.run(...)`
+
+```ts
+const result = await formatTicketTool.run({
+  title: 'Reset password',
+  priority: 'high',
+});
+```
+
+If the tool has `credentialSets` or `workflowGlobals`, pass an explicit context:
+
+```ts
+const result = await lookupCustomerTool.run(
+  { customerId: 'cus_123' },
+  {
+    credentials: {
+      crmApi: {
+        apiKey: 'test-key',
+      },
+    },
+    workflowGlobals: {
+      tenantId: 'tenant_123',
+    },
+  }
+);
+```
+
+## `Tool.configure(...)`
+
+```ts
+const renamedFormatTool = formatTicketTool.configure({
+  description: 'Formats a support ticket for CRM import.',
+});
+```
+
+## `Tool.mapInput(...)`
+
+```ts
+import { z } from 'zod';
+
+const formatTicketFromString = formatTicketTool.mapInput(
+  z.string(),
+  (title) => ({
+    title,
+    priority: 'medium',
+  })
+);
+```
+
+## `Tool.mapOutput(...)`
+
+```ts
+import { z } from 'zod';
+
+const formatTicketTextOnly = formatTicketTool.mapOutput(
+  z.string(),
+  (output) => output.text
+);
+```
+
+## `Tool.describe()` and `Tool.toManifest()`
+
+The same instance methods are available on `Operation`, because `Tool` is just the agent-oriented alias.
+
+```ts
+const toolSummary = formatTicketTool.describe();
+const toolManifest = formatTicketTool.toManifest();
+```
+
+## `skills`
+
+```ts
+import { anthropic } from '@keystroke/integration-ai';
+import { Agent } from '@keystrokehq/core';
+
+export const codingAgent = new Agent({
+  id: 'coding-agent',
+  name: 'Coding Agent',
+  systemPrompt: 'Use the installed skills before inventing your own process.',
+  model: 'anthropic/claude-sonnet-4-20250514',
+  credentialSets: [anthropic],
+  skills: [
+    { path: './.keystroke/skills/repo-linting' },
+    { registry: 'keystroke', name: 'typescript-review' },
+  ],
+});
+```
+
+Use `skills` when the agent runtime should have access to installed skills in addition to tools or MCP servers.
+
+## `configure(...)`
+
+```ts
+const renamedAgent = researchAgent.configure({
+  name: 'Renamed Research Agent',
+  maxSteps: 20,
+});
+```
+
+Use `configure(...)` to create a new agent instance with changed metadata or hooks.
+
+## `describe()` and `toManifest()`
+
+```ts
+const summary = researchAgent.describe();
+const manifest = researchAgent.toManifest();
+```
+
+Use `describe()` for a short human-readable summary and `toManifest()` when the caller needs the manifest form.