feat: API protocol implementation plan with kernel service extensions by Copilot · Pull Request #548 · objectstack-ai/objectstack

Copilot · 2026-02-08T08:24:04Z

Evaluates how the 61-method ObjectStackProtocolSchema maps to kernel services and plugins, defines REST endpoints, and extends the spec with the missing infrastructure.

Development Plan (`API_IMPLEMENTATION_PLAN.md`)

Maps all 14 protocol namespaces → CoreServices with ownership (3 required kernel-native, 12 plugin-provided)
Full REST endpoint table: 61 methods with HTTP verb, URL pattern, auth, owning service
Plugin roadmap: 11 plugins across 4 phases (P0 core gateway → P3 GraphQL)
4 ADRs: service degradation, package mgmt ownership, REST/WS boundary, hot-plug routing

Spec Changes

core-services.zod.ts — Add ai, i18n, ui, workflow to CoreServiceName enum and ServiceRequirementDef
discovery.zod.ts — Extend ApiRoutesSchema with 6 new optional route fields (packages, workflow, realtime, notifications, ai, i18n); extend ApiCapabilitiesSchema with 4 capability flags
dispatcher.zod.ts (new) — DispatcherRouteSchema / DispatcherConfigSchema / DEFAULT_DISPATCHER_ROUTES defining how HttpDispatcher routes URL prefixes to kernel services
manifest.zod.ts — Add contributes.routes so plugins can declare API route ownership:

contributes: {
  routes: [
    { prefix: '/api/v1/ai', service: 'ai', methods: ['aiNlq', 'aiChat'] }
  ],
}

dispatcher.test.ts (new) — 18 tests covering route validation, defaults, criticality levels, and DEFAULT_DISPATCHER_ROUTES completeness

All 3099 tests pass across 98 test files.

💡 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 · 2026-02-08T08:24:11Z

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

Project	Deployment	Actions	Updated (UTC)
objectstack-studio	Error		Feb 8, 2026 8:34am
spec	Ready	Preview, Comment	Feb 8, 2026 8:34am

…apping Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

… protocol, extend API routes Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Copilot

Pull request overview

Adds spec-level infrastructure to map ObjectStack’s API protocol namespaces to kernel services/plugins, including a dispatcher routing contract and an implementation plan document.

Changes:

Extends CoreServiceName (+ requirement defs) with ai, i18n, ui, workflow.
Expands Discovery schemas with additional capabilities flags and route fields.
Introduces api/dispatcher.zod.ts (+ tests) and adds contributes.routes to plugin manifests for dispatcher routing.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
packages/spec/src/system/core-services.zod.ts	Adds new core service identifiers and marks them optional in `ServiceRequirementDef`.
packages/spec/src/kernel/manifest.zod.ts	Adds `contributes.routes` for plugin-declared API prefix → service ownership.
packages/spec/src/api/index.ts	Exports the new dispatcher schema module.
packages/spec/src/api/dispatcher.zod.ts	Defines dispatcher route/config schemas and a default `/api/v1/*` routing table.
packages/spec/src/api/dispatcher.test.ts	Adds Vitest coverage for dispatcher schemas/defaults.
packages/spec/src/api/discovery.zod.ts	Adds new capability flags and optional routes for additional namespaces.
packages/spec/API_IMPLEMENTATION_PLAN.md	Provides a detailed protocol→service→REST mapping and phased implementation/ADR plan.

Copilot · 2026-02-08T08:59:13Z

+  fallback: z.enum(['404', 'proxy', 'custom']).default('404')
+    .describe('Behavior when no route matches'),
+


DispatcherConfigSchema supports fallback: 'proxy', but there’s no validation that proxyTarget is present in that case (and absent otherwise). Add a .superRefine/discriminated union so invalid configs (proxy fallback without target) don’t validate.

Copilot · 2026-02-08T08:59:13Z

+  criticality: ServiceCriticalitySchema.default('optional')
+    .describe('Service criticality level for unavailability handling'),


ServiceCriticalitySchema is described in core-services.zod.ts as a startup-time requirement level, but here it’s reused to drive request-time HTTP behavior when a service is unavailable. Either align the semantics/docstrings, or introduce a dedicated route-level enum to avoid conflating startup criticality with runtime HTTP behavior.

Copilot · 2026-02-08T08:59:13Z

+ * The dispatcher is the central routing component that:
+ * 1. Matches incoming request URLs against registered route prefixes
+ * 2. Delegates to the corresponding CoreService implementation
+ * 3. Returns 503 Service Unavailable when a service is not registered


Dispatcher doc says it "Returns 503 Service Unavailable when a service is not registered", but the criticality docs indicate some cases return 500. Please reconcile this documentation so it reflects the intended behavior consistently.

Suggested change

* 3. Returns 503 Service Unavailable when a service is not registered

* 3. Handles service unavailability (including unregistered services)

* according to the route's criticality policy

Copilot · 2026-02-08T08:59:14Z

+describe('DEFAULT_DISPATCHER_ROUTES', () => {
+  it('should have routes for all protocol namespaces', () => {
+    expect(DEFAULT_DISPATCHER_ROUTES.length).toBeGreaterThanOrEqual(14);
+  });


Test name says it verifies routes exist for all protocol namespaces, but the assertion only checks DEFAULT_DISPATCHER_ROUTES.length >= 14, which wouldn’t catch missing namespaces (or duplicates) as long as the array is long enough. Consider asserting the exact expected set of prefixes/namespaces to make this test meaningful.

Copilot · 2026-02-08T08:59:14Z

+  it('should accept proxy fallback with target', () => {
+    const config = DispatcherConfigSchema.parse({
+      routes: [],
+      fallback: 'proxy',
+      proxyTarget: 'https://api.example.com',


Add a negative test asserting DispatcherConfigSchema rejects fallback: 'proxy' when proxyTarget is missing (this will validate the conditional requirement logic for proxy mode).

Copilot · 2026-02-08T08:59:14Z

  hub: z.boolean().default(false).describe('Is Hub management enabled?'),
+  ai: z.boolean().default(false).describe('Is the AI engine enabled?'),
+  workflow: z.boolean().default(false).describe('Is the Workflow engine enabled?'),
+  notifications: z.boolean().default(false).describe('Is the Notification service enabled?'),
+  i18n: z.boolean().default(false).describe('Is the i18n service enabled?'),


ApiCapabilitiesSchema adds new feature flags (ai/workflow/notifications/i18n), but current discovery tests don’t exercise these fields (defaults or parsing). Add/extend tests to cover at least one new flag’s default and one enabled case to prevent silent regressions.

Copilot · 2026-02-08T08:59:14Z

+  /** Base URL for Package Management */
+  packages: z.string().optional().describe('e.g. /api/v1/packages'),
+
+  /** Base URL for Workflow Engine */
+  workflow: z.string().optional().describe('e.g. /api/v1/workflow'),


ApiRoutesSchema adds new optional routes (packages/workflow/realtime/notifications/ai/i18n), but current discovery tests don’t cover parsing of these new keys. Add a test case that includes a couple of these new route fields so the expansion doesn’t go untested.

Copilot · 2026-02-08T08:59:14Z

+      /** Service name this plugin provides */
+      service: z.string().describe('Service name this plugin provides'),
+      /** Protocol method names implemented */


In contributes.routes, service is currently z.string(), which allows arbitrary values that won’t match CoreServiceName and can break dispatcher routing. Consider importing CoreServiceName from ../system/core-services.zod and using it here so plugin manifests are validated against the known service registry.

Initial plan

7a6f185

Copilot AI assigned Copilot and hotlong Feb 8, 2026

Copilot started work on behalf of hotlong February 8, 2026 08:24 View session

vercel Bot had a problem deploying to Preview – objectstack-studio February 8, 2026 08:24 Failure

vercel Bot deployed to Preview – spec February 8, 2026 08:25 View deployment

docs: add API_IMPLEMENTATION_PLAN.md with full protocol-to-endpoint m…

0c34bd4

…apping Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

vercel Bot had a problem deploying to Preview – objectstack-studio February 8, 2026 08:29 Failure

vercel Bot deployed to Preview – spec February 8, 2026 08:30 View deployment

feat: extend kernel services with ai/i18n/ui/workflow, add dispatcher…

7cb7d71

… protocol, extend API routes Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

vercel Bot had a problem deploying to Preview – objectstack-studio February 8, 2026 08:32 Failure

vercel Bot deployed to Preview – spec February 8, 2026 08:34 View deployment

Copilot AI changed the title ~~[WIP] Evaluate plugin implementation for new API protocol~~ feat: API protocol implementation plan with kernel service extensions Feb 8, 2026

Copilot AI requested a review from hotlong February 8, 2026 08:36

Copilot finished work on behalf of hotlong February 8, 2026 08:36

hotlong marked this pull request as ready for review February 8, 2026 08:53

Copilot AI review requested due to automatic review settings February 8, 2026 08:53

Copilot started reviewing on behalf of hotlong February 8, 2026 08:53 View session

hotlong approved these changes Feb 8, 2026

View reviewed changes

hotlong merged commit 636f006 into main Feb 8, 2026
6 of 7 checks passed

Copilot AI reviewed Feb 8, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: API protocol implementation plan with kernel service extensions#548

feat: API protocol implementation plan with kernel service extensions#548
hotlong merged 3 commits into
mainfrom
copilot/evaluate-api-protocol-implementation

Copilot AI commented Feb 8, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Feb 8, 2026 •

edited

Loading

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 8, 2026

Uh oh!

Copilot AI Feb 8, 2026

Uh oh!

Copilot AI Feb 8, 2026

Uh oh!

Copilot AI Feb 8, 2026

Uh oh!

Copilot AI Feb 8, 2026

Uh oh!

Copilot AI Feb 8, 2026

Uh oh!

Copilot AI Feb 8, 2026

Uh oh!

Copilot AI Feb 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		fallback: z.enum(['404', 'proxy', 'custom']).default('404')
		.describe('Behavior when no route matches'),

		criticality: ServiceCriticalitySchema.default('optional')
		.describe('Service criticality level for unavailability handling'),

	* 3. Returns 503 Service Unavailable when a service is not registered
	* 3. Handles service unavailability (including unregistered services)
	* according to the route's criticality policy

Uh oh!

Conversation

Copilot AI commented Feb 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Development Plan (API_IMPLEMENTATION_PLAN.md)

Spec Changes

Uh oh!

vercel Bot commented Feb 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Feb 8, 2026 •

edited

Loading

Development Plan (`API_IMPLEMENTATION_PLAN.md`)

vercel Bot commented Feb 8, 2026 •

edited

Loading