Add: `runtime` field to Expert schema

[FL4TLiN3]

Overview

Add the runtime field to Expert schema in @perstack/core to support multi-runtime execution.

Background

The runtime field declares which runtimes an Expert is compatible with (similar to engines in package.json). This is a compatibility declaration, not parallel execution:

runtime = ["cursor", "claude-code"]  # Works on both, runs on ONE at a time

This enables:

• Publishing Experts that work across multiple runtimes
• Users choosing their preferred runtime via --runtime option
• Registry filtering by runtime compatibility

See: Multi-Runtime Support Documentation

Implementation

1. Add Runtime Name Type Definition

File: packages/core/src/schemas/runtime-name.ts (new file)

Create a new file to avoid confusion with runtime.ts (which contains RunEvent, RuntimeEvent, etc.):

import { z } from "zod"

export type RuntimeName = "perstack" | "cursor" | "claude-code" | "gemini"

export const runtimeNameSchema = z.enum(["perstack", "cursor", "claude-code", "gemini"])

Note: RuntimeName (execution environment) is semantically different from RuntimeEvent (infrastructure events). Separate file prevents confusion.

2. Update Expert Schema

File: packages/core/src/schemas/expert.ts

Add runtime field to Expert interface:

export interface Expert {
  // ... existing fields ...
  /** Target runtimes for this Expert (default: ["perstack"]) */
  runtime: RuntimeName[]
}

Add to expertSchema:

export const expertSchema = z.object({
  // ... existing fields ...
  runtime: z
    .union([
      runtimeNameSchema,
      z.array(runtimeNameSchema),
    ])
    .optional()
    .default(["perstack"])
    .transform((value) => (typeof value === "string" ? [value] : value)),
})

3. Update PerstackConfig Expert Schema

File: packages/core/src/schemas/perstack-toml.ts

Add runtime field to PerstackConfigExpert:

export interface PerstackConfigExpert {
  // ... existing fields ...
  /** Target runtimes (default: ["perstack"]) */
  runtime?: RuntimeName | RuntimeName[]
}

Update perstackConfigSchema.experts:

z.object({
  // ... existing fields ...
  runtime: z
    .union([
      runtimeNameSchema,
      z.array(runtimeNameSchema),
    ])
    .optional(),
})

4. Export New Types

File: packages/core/src/index.ts

Add exports:

export type { RuntimeName } from "./schemas/runtime-name.js"
export { runtimeNameSchema } from "./schemas/runtime-name.js"

Affected Files

File	Change
packages/core/src/schemas/runtime-name.ts	New: RuntimeName type and schema
packages/core/src/schemas/expert.ts	Add runtime field, import RuntimeName
packages/core/src/schemas/perstack-toml.ts	Add runtime field, import RuntimeName
packages/core/src/index.ts	Export new types from runtime-name.ts

Testing

Add tests in packages/core/src/schemas/expert.test.ts:

1. Default runtime value is ["perstack"]
2. Single string "cursor" transforms to ["cursor"]
3. Array ["cursor", "claude-code"] is preserved
4. Invalid runtime name is rejected

Example test:

describe("runtime field", () => {
  it("defaults to perstack", () => {
    const result = expertSchema.parse({
      key: "test",
      name: "test",
      version: "1.0.0",
      instruction: "test",
    })
    expect(result.runtime).toEqual(["perstack"])
  })

  it("transforms single string to array", () => {
    const result = expertSchema.parse({
      key: "test",
      name: "test",
      version: "1.0.0",
      instruction: "test",
      runtime: "cursor",
    })
    expect(result.runtime).toEqual(["cursor"])
  })

  it("preserves array", () => {
    const result = expertSchema.parse({
      key: "test",
      name: "test",
      version: "1.0.0",
      instruction: "test",
      runtime: ["cursor", "claude-code"],
    })
    expect(result.runtime).toEqual(["cursor", "claude-code"])
  })

  it("rejects invalid runtime", () => {
    expect(() =>
      expertSchema.parse({
        key: "test",
        name: "test",
        version: "1.0.0",
        instruction: "test",
        runtime: "invalid",
      }),
    ).toThrow()
  })
})

Documentation

No additional documentation needed (already documented in multi-runtime.mdx).

Acceptance Criteria

• RuntimeName type exported from @perstack/core
• runtimeNameSchema exported from @perstack/core
• Expert.runtime field defaults to ["perstack"]
• Single string runtime transforms to array
• Invalid runtime names are rejected
• All tests pass
• pnpm typecheck passes

Dependencies

None (this is the first issue in the implementation chain)

Blocked By

None

Blocks

• chore: version packages #2 CLI --runtime option
• Fix: maxSteps off-by-one error #3 RuntimeAdapter interface

[github-actions]

Status Update for Issue #89

I've reviewed the codebase and can confirm that the runtime field feature has not been implemented yet. Here's what I found:

Current State

• ❌ No runtime-name.ts file exists in packages/core/src/schemas/
• ❌ Expert interface in expert.ts does not have a runtime field
• ❌ PerstackConfigExpert in perstack-toml.ts does not have a runtime field
• ❌ No runtime-related exports in packages/core/src/index.ts

Implementation Validation

The proposed implementation looks solid and follows the existing codebase patterns:

✅ Separate file for RuntimeName: Creating runtime-name.ts is the right approach since runtime.ts already contains infrastructure types (RuntimeEvent, RunEvent, etc.) that are semantically different from execution environment names.

✅ Schema structure: The proposed Zod schema with .union(), .optional(), .default(), and .transform() matches the patterns used in other schemas like expert.ts (see the delegates and tags fields).

✅ Type definitions: The RuntimeName type and runtimeNameSchema follow the same pattern as other enums in the codebase.

Recommendations

1. Test coverage: The proposed tests in the issue are comprehensive and cover all edge cases (default value, string-to-array transformation, array preservation, and validation).

2. Backward compatibility: The default value of ["perstack"] ensures backward compatibility with existing Expert definitions.

3. Consider adding: You might want to add a helper function to check runtime compatibility, similar to how parseExpertKey exists in runtime.ts.

The implementation is ready to proceed as specified in the issue. All the affected files and changes are clearly documented.

---

🤖 Bot Activity

✅ Done
---

[FL4TLiN3]

Completed in PR #101