Merge pull request #94 from AgentWorkforce/ricky/sage-214-pr01a-persona-types

feat(persona): add shared persona type package

Author: khaliqgant

package-lock.json

@@ -8,6 +8,7 @@
     "packages/vfs",
     "packages/harness",
     "packages/memory",
+    "packages/persona",
     "packages/inbox",
     "packages/continuation",
     "packages/turn-context",

package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@agent-assistant/persona",
+  "version": "0.1.0",
+  "description": "Shared persona type contracts for agent assistant services",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prepack": "npm run build",
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "license": "MIT"
+}

packages/persona/package.json

@@ -0,0 +1,9 @@
+export type {
+  PersonaDefinition,
+  PersonaDeliveryConfig,
+  PersonaExecutor,
+  PersonaMemoryConfig,
+  PersonaTrigger,
+  RouterConfig,
+  SandboxBorrowConfig,
+} from "./types.js";

packages/persona/src/index.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from "vitest";
+import type { PersonaDefinition } from "./types.js";
+
+describe("persona type contracts", () => {
+  it("supports ephemeral sandbox executors", () => {
+    const persona = {
+      id: "daily-research",
+      displayName: "Daily Research",
+      version: "0.1.0",
+      ownerService: "sage",
+      executor: { kind: "ephemeral-sandbox" },
+      triggers: [{ kind: "cron", cron: "0 9 * * *", timezone: "UTC" }],
+    } satisfies PersonaDefinition;
+
+    expect(persona.executor.kind).toBe("ephemeral-sandbox");
+  });
+
+  it("supports HTTP delegate executors", () => {
+    const persona = {
+      id: "nightcto-triage",
+      displayName: "NightCTO Triage",
+      version: "0.1.0",
+      ownerService: "nightcto",
+      executor: {
+        kind: "http-delegate",
+        router: {
+          endpoint: "https://example.com/personas/nightcto",
+          method: "POST",
+          timeoutMs: 30_000,
+          headers: { "x-persona": "nightcto" },
+        },
+      },
+      triggers: [{ kind: "webhook", provider: "github", event: "issue.opened" }],
+      delivery: { mode: "callback", callbackUrl: "https://example.com/callback" },
+    } satisfies PersonaDefinition;
+
+    expect(persona.executor.kind).toBe("http-delegate");
+  });
+
+  it("supports hybrid executors", () => {
+    const persona = {
+      id: "msd-app-helper",
+      displayName: "MSD App Helper",
+      version: "0.1.0",
+      ownerService: "msd-app",
+      executor: {
+        kind: "hybrid",
+        router: {
+          endpoint: "https://example.com/personas/msd",
+        },
+        sandbox: {
+          snapshot: "persona-msd-base",
+          lifecycle: "warm-pool",
+          ttlSeconds: 600,
+          maxConcurrentBorrows: 3,
+          capabilities: ["repo-read", "browser"],
+        },
+      },
+      triggers: [{ kind: "inbox", channel: "support", event: "message.created" }],
+      memory: { backend: "agent-memory", namespace: "msd-app" },
+      metadata: { tier: "support" },
+    } satisfies PersonaDefinition;
+
+    expect(persona.executor.kind).toBe("hybrid");
+  });
+});

packages/persona/src/types.test.ts

@@ -0,0 +1,48 @@
+export interface RouterConfig {
+  endpoint: string;
+  method?: "POST";
+  timeoutMs?: number;
+  headers?: Record<string, string>;
+}
+
+export interface SandboxBorrowConfig {
+  snapshot: string;
+  lifecycle?: "ephemeral" | "warm-pool";
+  ttlSeconds?: number;
+  maxConcurrentBorrows?: number;
+  capabilities?: string[];
+}
+
+export type PersonaExecutor =
+  | { kind: "ephemeral-sandbox" }
+  | { kind: "http-delegate"; router: RouterConfig }
+  | { kind: "hybrid"; router: RouterConfig; sandbox: SandboxBorrowConfig };
+
+export type PersonaTrigger =
+  | { kind: "cron"; cron: string; timezone?: string; name?: string }
+  | { kind: "webhook"; provider: string; event?: string; path?: string }
+  | { kind: "inbox"; channel?: string; event?: string };
+
+export interface PersonaMemoryConfig {
+  backend?: "agent-memory" | "supermemory" | "none";
+  namespace?: string;
+}
+
+export interface PersonaDeliveryConfig {
+  mode?: "inline" | "callback" | "direct";
+  callbackUrl?: string;
+}
+
+export interface PersonaDefinition {
+  id: string;
+  displayName: string;
+  version: string;
+  description?: string;
+  ownerService?: "sage" | "nightcto" | "msd-app" | "workforce" | (string & {});
+  sourceTag?: string;
+  executor: PersonaExecutor;
+  triggers?: PersonaTrigger[];
+  memory?: PersonaMemoryConfig;
+  delivery?: PersonaDeliveryConfig;
+  metadata?: Record<string, unknown>;
+}

packages/persona/src/types.ts

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "exactOptionalPropertyTypes": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "noUncheckedIndexedAccess": true
+  },
+  "include": [
+    "src/**/*.ts"
+  ]
+}