Fix Automation API contract type safety and complete triggerFlow schema

[Copilot]

IAutomationService contract methods returned unknown instead of proper schema types, and triggerFlow was the only endpoint in AutomationApiContracts missing input/output schemas.

Contract type safety

• getFlow → Promise<FlowParsed | null> (was unknown | null)
• listRuns → Promise<ExecutionLog[]> (was unknown[])
• getRun → Promise<ExecutionLog | null> (was unknown | null)

TriggerFlow schema gap

• Added TriggerFlowRequestSchema (name, record, object, event, userId, params)
• Added TriggerFlowResponseSchema (success, output, error, durationMs)
• All 9 AutomationApiContracts entries now have input/output

// Before
getFlow?(name: string): Promise<unknown | null>;
listRuns?(flowName: string, options?: { limit?: number; cursor?: string }): Promise<unknown[]>;

// After
getFlow?(name: string): Promise<FlowParsed | null>;
listRuns?(flowName: string, options?: { limit?: number; cursor?: string }): Promise<ExecutionLog[]>;

Tests

• Contract tests verify typed returns (FlowParsed, ExecutionLog) for getFlow, listRuns, getRun, toggleFlow
• API tests cover TriggerFlowRequestSchema/TriggerFlowResponseSchema parsing
• Contract registry assertion: all 9 endpoints have input and output defined

ROADMAP

• Updated contract matrix and automation section to reflect typed returns and full schema coverage

Original prompt

---

This section details on the original issue you should resolve

<issue_title>补全 Automation API 服务端与路由实现、接口契约及测试覆盖</issue_title>
<issue_description>## Automation API 完成度补全任务：Spec/Runtime/测试全链路

背景

根据 Issue objectstack-ai/spec#757 的交付内容审查，发现 Automation API 的 protocol schema、Client SDK 层面已基本实现，但 contract、Engine 执行历史及 HTTP route handler 等 Runtime/服务端内容尚未开发或未完善。同时 schema 测试和 contract matrix 也未进行严格验证，ROADMAP 标记与代码实现不一致。需补齐薄弱环节，闭环 API、服务、路由、测试链路。

---

待开发内容清单

1️⃣ Contract/接口扩展

• 在 contracts/automation-service.ts 中新增以下 IAutomationService 可选方法：
  • getFlow?(name: string): Promise<FlowDefinition | null>
  • toggleFlow?(name: string, enabled: boolean): Promise<void>
  • listRuns?(flowName: string, options?: { limit?: number; cursor?: string }): Promise<ExecutionLog[]>
  • getRun?(runId: string): Promise<ExecutionLog | null>
• 编写 contract 合约测试，确保类型兼容性
• 更新 Contract Implementation Matrix

2️⃣ Engine 服务实现

• 在 AutomationEngine （service-automation/src/engine.ts）新增执行历史存储（run log/step log）
• 实现上述 IAutomationService 新增方法：
  • getFlow — 查询 flow 定义
  • toggleFlow — enable/disable 标记
  • listRuns — 查询执行历史
  • getRun — 查询单次执行详情
• 每次 execute() 记录 ExecutionLog，支持 runId 流水存档
• 为以上方法编写测试用例

3️⃣ HTTP 路由 handler 扩展

• 扩展 runtime/src/http-dispatcher.ts 的 handleAutomation()，新增以下路由分支
  • GET /automation → listFlows
  • GET /automation/:name → getFlow
  • POST /automation → createFlow
  • PUT /automation/:name → updateFlow
  • DELETE /automation/:name → deleteFlow
  • POST /automation/:name/trigger → execute
  • POST /automation/:name/toggle → toggleFlow
  • GET /automation/:name/runs → listRuns
  • GET /automation/:name/runs/:runId → getRun
• 在 createDispatcherPlugin() 注册对应 server 路由
• 编写路由 handler 测试

4️⃣ 测试与持续交付

• 创建 packages/spec/src/api/automation-api.test.ts，补齐 Automation API schema 单测
• 完善 pnpm test 测试覆盖至新增 contract、engine 及路由
• 完成后严格检查 ROADMAP checklist 与实际代码同步

---

补充

补全后需运行 test，并及时更新 ROADMAP.md、Contract/Package Matrix，确保 Spec, Service, Router, Client, Test 全链路一致。

---

关联

• 原任务：Issue objectstack-ai/spec#757
• ROADMAP Section 2 — Automation API</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes 补全 Automation API 服务端与路由实现、接口契约及测试覆盖 #764

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
objectstack-play	Ready	Preview, Comment	Feb 21, 2026 8:46am
spec	Ready	Preview, Comment	Feb 21, 2026 8:46am

[Copilot]

Pull request overview

This PR completes the Automation API contract type safety improvements by replacing unknown types with properly typed schema types (FlowParsed, ExecutionLog) and adding the missing input/output schemas for the triggerFlow endpoint. This ensures all 9 AutomationApiContracts entries have complete schema definitions for runtime validation and TypeScript type safety.

Changes:

• Updated IAutomationService contract to use typed returns: getFlow → FlowParsed | null, listRuns → ExecutionLog[], getRun → ExecutionLog | null
• Added TriggerFlowRequestSchema and TriggerFlowResponseSchema to complete the API protocol definition
• Added comprehensive contract tests verifying typed returns for getFlow, listRuns, getRun, and toggleFlow
• Updated ROADMAP to reflect completed type safety improvements and full schema coverage

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
packages/spec/src/contracts/automation-service.ts	Added imports for FlowParsed and ExecutionLog; updated return types from unknown to properly typed schemas
packages/spec/src/contracts/automation-service.test.ts	Added 3 new test cases for getFlow, listRuns/getRun, and toggleFlow with typed returns
packages/spec/src/api/automation-api.zod.ts	Added TriggerFlowRequestSchema and TriggerFlowResponseSchema; updated triggerFlow contract entry with input/output schemas
packages/spec/src/api/automation-api.test.ts	Added tests for TriggerFlow request/response parsing; added assertion that all endpoints have input/output schemas
ROADMAP.md	Updated automation section to reflect typed returns and complete schema coverage in contract matrix

[Copilot]

The FlowSchema does not have an enabled field. According to the FlowSchema in automation/flow.zod.ts, flows use active (boolean, deprecated) and status (enum: 'draft', 'active', 'obsolete', 'invalid') instead. This test will fail when the mock flow is validated against the actual schema. Consider using active: true or status: 'active' instead.

Suggested change

enabled: true,