refactor: migrate from syncpoint-core to syncpoint-adapters, syncpoint-kernel, and syncpoint-context

- Updated imports across multiple repositories to replace syncpoint-core with syncpoint-adapters, syncpoint-kernel, and syncpoint-context.
- Adjusted type imports accordingly to reflect the new structure.
- Modified tsconfig.json files to include new path mappings for the updated packages.
- Ensured all references in tests and routers are aligned with the new package structure.

Author: MIK-HEAL

packages/syncpoint-adapters/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "syncpoint-adapters",
+  "version": "0.1.0",
+  "description": "SyncPoint adapters/orchestration layer — external integration surfaces",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist"],
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "syncpoint-kernel": "workspace:*",
+    "syncpoint-governance": "workspace:*",
+    "syncpoint-context": "workspace:*",
+    "yaml": "^2.4.2",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0"
+  }
+}

packages/syncpoint-adapters/src/adapter.ts

@@ -0,0 +1,225 @@
+/**
+ * Agent Adapter Protocol — standardized interface for AI editor integration.
+ *
+ * Each adapter defines how a specific AI editor (Codex, Claude Code, Cursor, Cline)
+ * should consume SyncPoint's resume context at key lifecycle moments:
+ *
+ *   onBoot    — agent starts fresh or is assigned a task
+ *   onResume  — agent resumes after pause / context switch
+ *   onHandoff — agent receives a task handoff from another agent
+ *
+ * The adapter protocol does NOT control the editor directly.
+ * It produces the correct files and instructions so that the editor's native
+ * mechanism picks up the narrowed context.
+ */
+
+import { z } from "zod";
+import type { ResumeContext } from "syncpoint-context";
+import type { PromptFormat } from "syncpoint-context";
+
+// ── Provider enum ────────────────────────────────────
+
+export const AgentProvider = z.enum([
+  "codex",
+  "claude-code",
+  "cursor",
+  "cline",
+  "copilot",
+  "human",
+  "other",
+]);
+export type AgentProvider = z.infer<typeof AgentProvider>;
+
+// ── Lifecycle events ─────────────────────────────────
+
+export const AdapterLifecycleEvent = z.enum([
+  "boot",
+  "resume",
+  "handoff",
+  "checkpoint",
+]);
+export type AdapterLifecycleEvent = z.infer<typeof AdapterLifecycleEvent>;
+
+// ── Adapter instruction ──────────────────────────────
+
+export const AdapterInstructionSchema = z.object({
+  /** Lifecycle event that triggered this instruction */
+  event: AdapterLifecycleEvent,
+  /** Provider this instruction targets */
+  provider: AgentProvider,
+  /** Files to write (relative path → content) */
+  files: z.record(z.string()),
+  /** Formatted prompt text for clipboard / system prompt injection */
+  promptText: z.string(),
+  /** Format used for the primary rules file */
+  primaryFormat: z.string(),
+  /** Human-readable summary of what the adapter did */
+  summary: z.string(),
+  /** Warnings from resume context */
+  warnings: z.array(z.string()),
+  /** Whether the context is ready */
+  ready: z.boolean(),
+});
+
+export type AdapterInstruction = z.infer<typeof AdapterInstructionSchema>;
+
+// ── Adapter config per provider ──────────────────────
+
+export interface AdapterConfig {
+  /** Which provider this adapter serves */
+  provider: AgentProvider;
+  /** Primary rules file format */
+  rulesFormat: PromptFormat;
+  /** File path for the primary rules file (relative to project root) */
+  rulesFile: string;
+  /** Additional files to generate */
+  extraFiles: { path: string; format: PromptFormat }[];
+  /** System prompt preamble injected before resume context */
+  preamble: string;
+  /** Instructions shown to the user about how to configure the editor */
+  setupInstructions: string;
+}
+
+// ── Built-in adapter configs ─────────────────────────
+
+export const ADAPTER_CONFIGS: Record<string, AdapterConfig> = {
+  cursor: {
+    provider: "cursor",
+    rulesFormat: "cursorrules",
+    rulesFile: ".cursorrules",
+    extraFiles: [],
+    preamble:
+      "You are working on a SyncPoint-managed project. " +
+      "The rules below are your ONLY source of task context. " +
+      "Do NOT use previous conversation history.",
+    setupInstructions:
+      "Cursor reads .cursorrules automatically from the project root.\n" +
+      "Run `syncpoint adapter boot` after each resume or handoff.\n" +
+      "The .cursorrules file will be overwritten with the latest context.",
+  },
+
+  "claude-code": {
+    provider: "claude-code",
+    rulesFormat: "agents-md",
+    rulesFile: "AGENTS.md",
+    extraFiles: [
+      { path: ".syncpoint/resume-prompt.md", format: "system-prompt" },
+    ],
+    preamble:
+      "You are working on a SyncPoint-managed project. " +
+      "Read AGENTS.md for your current task context. " +
+      "Do NOT carry over previous conversation history.",
+    setupInstructions:
+      "Claude Code reads AGENTS.md as project knowledge.\n" +
+      "Run `syncpoint adapter boot` after each resume or handoff.\n" +
+      "Start new conversations with: /read AGENTS.md",
+  },
+
+  codex: {
+    provider: "codex",
+    rulesFormat: "agents-md",
+    rulesFile: "AGENTS.md",
+    extraFiles: [
+      { path: ".syncpoint/resume-prompt.md", format: "system-prompt" },
+    ],
+    preamble:
+      "You are working on a SyncPoint-managed project. " +
+      "Read AGENTS.md for your current task context. " +
+      "Do NOT carry over previous conversation history.",
+    setupInstructions:
+      "Codex reads AGENTS.md as project context.\n" +
+      "Run `syncpoint adapter boot` after each resume or handoff.\n" +
+      "Pass --system-prompt from .syncpoint/resume-prompt.md when using API.",
+  },
+
+  cline: {
+    provider: "cline",
+    rulesFormat: "system-prompt",
+    rulesFile: ".syncpoint/resume-prompt.md",
+    extraFiles: [
+      { path: ".cursorrules", format: "cursorrules" },
+    ],
+    preamble:
+      "You are working on a SyncPoint-managed project. " +
+      "The system prompt below is your ONLY source of task context. " +
+      "Do NOT use previous conversation history.",
+    setupInstructions:
+      "Cline uses system prompts from its settings.\n" +
+      "Run `syncpoint adapter boot` after each resume or handoff.\n" +
+      "Copy .syncpoint/resume-prompt.md into Cline's custom system prompt field.",
+  },
+
+  copilot: {
+    provider: "copilot",
+    rulesFormat: "agents-md",
+    rulesFile: "AGENTS.md",
+    extraFiles: [],
+    preamble:
+      "You are working on a SyncPoint-managed project. " +
+      "Read AGENTS.md for context.",
+    setupInstructions:
+      "GitHub Copilot reads AGENTS.md for project context.\n" +
+      "Run `syncpoint adapter boot` after each resume or handoff.",
+  },
+};
+
+// ── Build adapter instruction ────────────────────────
+
+import { formatResumePrompt } from "syncpoint-context";
+import type { RealityProjection } from "syncpoint-context";
+
+/**
+ * Build an AdapterInstruction for a given provider and lifecycle event.
+ * This produces the file contents and prompt text that should be written
+ * to the project directory so the editor picks up the narrowed context.
+ */
+export function buildAdapterInstruction(
+  ctx: ResumeContext,
+  provider: AgentProvider,
+  event: AdapterLifecycleEvent = "resume",
+  projection?: RealityProjection | null,
+): AdapterInstruction {
+  const config = ADAPTER_CONFIGS[provider] ?? ADAPTER_CONFIGS["cursor"]!;
+
+  const files: Record<string, string> = {};
+
+  // Primary rules file — P2: pass projection to all formats
+  const primaryContent = formatResumePrompt(ctx, config.rulesFormat, projection);
+  files[config.rulesFile] = primaryContent;
+
+  // Extra files
+  for (const extra of config.extraFiles) {
+    files[extra.path] = formatResumePrompt(ctx, extra.format, projection);
+  }
+
+  // Prompt text for clipboard / API injection
+  const promptText = config.preamble + "\n\n" + formatResumePrompt(ctx, "system-prompt", projection);
+
+  const fileList = Object.keys(files).join(", ");
+  const summary = `[${event}] ${config.provider}: wrote ${fileList}`;
+
+  return {
+    event,
+    provider: config.provider,
+    files,
+    promptText,
+    primaryFormat: config.rulesFormat,
+    summary,
+    warnings: ctx.warnings,
+    ready: ctx.ready,
+  };
+}
+
+/**
+ * Get adapter config for a provider. Returns undefined if not found.
+ */
+export function getAdapterConfig(provider: string): AdapterConfig | undefined {
+  return ADAPTER_CONFIGS[provider];
+}
+
+/**
+ * List all known adapter provider names.
+ */
+export function listAdapterProviders(): string[] {
+  return Object.keys(ADAPTER_CONFIGS);
+}

packages/syncpoint-adapters/src/agent-card.ts

@@ -0,0 +1,90 @@
+import { z } from "zod";
+import { AgentStatus } from "./states.js";
+import { AgentCapabilitySchema, AgentAvailability } from "./agent-manifest.js";
+import type { AgentManifest } from "./agent-manifest.js";
+import { AgentRoleSchema, UserAgentProviderSchema } from "./agent-file-manifest.js";
+import type { UserAgentManifest } from "./agent-file-manifest.js";
+import type { Agent } from "./models.js";
+import { toUserAgentManifestFromRuntime } from "./agent-manifest-conversion.js";
+
+export const AgentCardEndpointSchema = z.object({
+  kind: z.string().min(1),
+  url: z.string().min(1),
+});
+
+export type AgentCardEndpoint = z.infer<typeof AgentCardEndpointSchema>;
+
+export const AgentCardSchema = z.object({
+  schema: z.literal("syncpoint/agent-card/v1"),
+  agentId: z.string().nullable().default(null),
+  manifestPath: z.string().nullable().default(null),
+  name: z.string().min(1),
+  profile: z.string().min(1),
+  role: AgentRoleSchema,
+  provider: UserAgentProviderSchema,
+  status: z.nativeEnum(AgentStatus).nullable().default(null),
+  availability: z.nativeEnum(AgentAvailability).default(AgentAvailability.ONLINE),
+  tags: z.array(z.string()).default([]),
+  capabilities: z.array(AgentCapabilitySchema).default([]),
+  notes: z.string().default(""),
+  canHandleHumanEscalation: z.boolean().default(false),
+  protocols: z.array(z.string()).default(["syncpoint", "a2a-like"]),
+  endpoints: z.array(AgentCardEndpointSchema).default([]),
+  metadata: z.record(z.string()).default({}),
+});
+
+export type AgentCard = z.infer<typeof AgentCardSchema>;
+
+type AgentCardRuntimeManifestSource = Partial<
+  Pick<
+    AgentManifest,
+    "capabilities" | "escalationPreference" | "availability" | "canHandleHumanEscalation" | "tags"
+  >
+>;
+
+export interface BuildAgentCardInput {
+  manifestPath?: string | null;
+  agent?: Pick<Agent, "id" | "name" | "provider" | "role" | "status"> | null;
+  declaredManifest?: UserAgentManifest | null;
+  runtimeManifest?: AgentCardRuntimeManifestSource | null;
+  endpoints?: AgentCardEndpoint[];
+  metadata?: Record<string, string>;
+}
+
+export function buildAgentCard(input: BuildAgentCardInput): AgentCard {
+  const manifest = resolveCardManifest(input);
+  if (!manifest) {
+    throw new Error("Cannot build agent card without a declared or derived manifest.");
+  }
+
+  return AgentCardSchema.parse({
+    schema: "syncpoint/agent-card/v1",
+    agentId: input.agent?.id ?? null,
+    manifestPath: input.manifestPath ?? null,
+    name: manifest.name,
+    profile: manifest.profile,
+    role: manifest.role,
+    provider: manifest.provider,
+    status: input.agent?.status ?? null,
+    availability: manifest.availability,
+    tags: manifest.tags,
+    capabilities: manifest.capabilities,
+    notes: manifest.notes,
+    canHandleHumanEscalation: manifest.canHandleHumanEscalation,
+    protocols: ["syncpoint", "a2a-like"],
+    endpoints: input.endpoints ?? [],
+    metadata: {
+      source: input.declaredManifest ? "declared" : "runtime-derived",
+      ...(input.metadata ?? {}),
+    },
+  });
+}
+
+function resolveCardManifest(input: BuildAgentCardInput): UserAgentManifest | null {
+  if (input.declaredManifest) return input.declaredManifest;
+  if (!input.agent) return null;
+  return toUserAgentManifestFromRuntime({
+    agent: input.agent,
+    runtimeManifest: input.runtimeManifest,
+  });
+}