@levelcode/sdk 0.1.0 → 0.2.0

package/dist/packages/agent-runtime/src/inbox-poller.d.ts

@@ -0,0 +1,81 @@
+import type { TeamProtocolMessage } from '@levelcode/common/types/team-protocol';
+import type { Logger } from '@levelcode/common/types/contracts/logger';
+export interface InboxPollerConfig {
+    teamName: string;
+    agentName: string;
+    pollIntervalMs?: number;
+    logger: Logger;
+}
+export interface InboxPollResult {
+    messages: TeamProtocolMessage[];
+    formattedContent: string | null;
+}
+/**
+ * InboxPoller continuously polls an agent's inbox file for new messages
+ * and provides them in a format suitable for injection into the agent's
+ * next prompt turn.
+ *
+ * Usage:
+ *   const poller = new InboxPoller({ teamName, agentName, logger })
+ *   poller.start()
+ *   // Between agent turns:
+ *   const result = poller.drain()
+ *   if (result.formattedContent) {
+ *     // inject into message history
+ *   }
+ *   // When agent shuts down:
+ *   poller.stop()
+ */
+export declare class InboxPoller {
+    private teamName;
+    private agentName;
+    private pollIntervalMs;
+    private logger;
+    private timer;
+    private pendingMessages;
+    private running;
+    constructor(config: InboxPollerConfig);
+    /**
+     * Start polling the inbox file at the configured interval.
+     */
+    start(): void;
+    /**
+     * Stop polling.
+     */
+    stop(): void;
+    /**
+     * Poll the inbox once and accumulate any new messages.
+     * Messages are read from the filesystem and the inbox is cleared
+     * after reading to prevent duplicate delivery.
+     */
+    private poll;
+    /**
+     * Drain all accumulated pending messages and return them.
+     * After calling drain(), the internal buffer is cleared.
+     * Returns both the raw messages and a formatted string suitable
+     * for injection into the agent's message history.
+     */
+    drain(): InboxPollResult;
+    /**
+     * Check if there are any pending messages without draining them.
+     */
+    hasPendingMessages(): boolean;
+    /**
+     * Force an immediate poll (useful before draining between turns).
+     */
+    pollNow(): void;
+    /**
+     * Returns whether the poller is currently running.
+     */
+    isRunning(): boolean;
+}
+/**
+ * One-shot convenience function: reads the inbox, formats messages,
+ * clears the inbox, and returns the result. Useful when you don't need
+ * continuous background polling and just want to check between turns.
+ */
+export declare function drainInbox(params: {
+    teamName: string;
+    agentName: string;
+    logger: Logger;
+}): InboxPollResult;

package/dist/packages/agent-runtime/src/message-formatter.d.ts

@@ -0,0 +1,12 @@
+import type { TeamProtocolMessage } from '@levelcode/common/types/team-protocol';
+/**
+ * Formats a single TeamProtocolMessage into a human-readable string
+ * suitable for injection into an agent's message history.
+ */
+export declare function formatTeamMessage(message: TeamProtocolMessage): string;
+/**
+ * Formats an array of TeamProtocolMessages into a single string block
+ * wrapped in a system-level container tag, ready for injection into
+ * the agent's message history.
+ */
+export declare function formatInboxMessages(messages: TeamProtocolMessage[]): string | null;

package/dist/packages/agent-runtime/src/system-prompt/team-context-prompt.d.ts

@@ -0,0 +1,9 @@
+import type { DevPhase, TeamRole } from '@levelcode/common/types/team-config';
+export interface TeamContextPromptConfig {
+    teamName: string;
+    agentName: string;
+    role: TeamRole;
+    phase: DevPhase;
+    isLeader: boolean;
+}
+export declare function generateTeamContextPrompt(config: TeamContextPromptConfig): string;

package/dist/packages/agent-runtime/src/system-prompt/team-prompt.d.ts

@@ -0,0 +1,9 @@
+import type { DevPhase, TeamRole } from '@levelcode/common/types/team-config';
+/**
+ * Generates a system prompt section explaining the agent's team context.
+ * This is the primary entry point for injecting team awareness into agent system prompts.
+ *
+ * Delegates to generateTeamContextPrompt for role-based guidance, communication
+ * protocols, task workflows, idle behavior, and shutdown instructions.
+ */
+export declare function generateTeamPromptSection(teamName: string, agentName: string, role: TeamRole, phase: DevPhase): string;

package/dist/packages/agent-runtime/src/team-context.d.ts

@@ -0,0 +1,14 @@
+import type { TeamConfig } from '@levelcode/common/types/team-config';
+export interface TeamContext {
+    teamName: string;
+    agentName: string;
+    config: TeamConfig;
+}
+/**
+ * Discovers the team context for a given agent identifier.
+ * Scans all team directories to find which team the agent belongs to.
+ * Matches against both the raw agentId and a "lead-" prefixed variant.
+ *
+ * Returns null if the agent is not part of any team (e.g., standalone mode).
+ */
+export declare function findTeamContext(agentIdentifier: string): TeamContext | null;

package/dist/packages/agent-runtime/src/templates/agent-registry.d.ts

@@ -18,7 +18,7 @@ export declare function getAgentTemplate(params: {
     logger: Logger;
 } & ParamsExcluding<FetchAgentFromDatabaseFn, 'parsedAgentId'>): Promise<AgentTemplate | null>;
 /**
- * Assemble local agent templates from fileContext + static templates
+ * Assemble local agent templates from fileContext + static templates + team agents
  */
 export declare function assembleLocalAgentTemplates(params: {
     fileContext: ProjectFileContext;

package/dist/packages/agent-runtime/src/tools/handlers/list.d.ts

@@ -194,6 +194,7 @@ export declare const levelcodeToolHandlers: {
         logger: import("@levelcode/common/types/contracts/logger").Logger;
         system: string;
         tools?: import("ai").ToolSet;
+        trackEvent: import("@levelcode/common/types/contracts/analytics").TrackEventFn;
         userId: string | undefined;
         userInputId: string;
         sendSubagentChunk: import("./tool/spawn-agents").SendSubagentChunk;
@@ -237,9 +238,15 @@ export declare const levelcodeToolHandlers: {
     }) => Promise<{
         output: import("src").LevelCodeToolOutput<"suggest_followups">;
     }>;
-    task_completed: ({ previousToolCallFinished, }: {
+    task_completed: ({ previousToolCallFinished, trackEvent, userId, logger, agentTemplate, }: {
         previousToolCallFinished: Promise<any>;
         toolCall: import("@levelcode/common/tools/list").LevelCodeToolCall<"task_completed">;
+        trackEvent: import("@levelcode/common/types/contracts/analytics").TrackEventFn;
+        userId: string | undefined;
+        logger: import("@levelcode/common/types/contracts/logger").Logger;
+        agentTemplate: {
+            name: string;
+        };
     }) => Promise<{
         output: import("src").LevelCodeToolOutput<"task_completed">;
     }>;
@@ -264,6 +271,9 @@ export declare const levelcodeToolHandlers: {
     task_update: (params: {
         previousToolCallFinished: Promise<void>;
         toolCall: import("@levelcode/common/tools/list").LevelCodeToolCall<"task_update">;
+        trackEvent: import("@levelcode/common/types/contracts/analytics").TrackEventFn;
+        userId: string | undefined;
+        logger: import("@levelcode/common/types/contracts/logger").Logger;
     }) => Promise<{
         output: import("src").LevelCodeToolOutput<"task_update">;
     }>;
@@ -271,6 +281,9 @@ export declare const levelcodeToolHandlers: {
         previousToolCallFinished: Promise<void>;
         toolCall: import("@levelcode/common/tools/list").LevelCodeToolCall<"send_message">;
         agentStepId: string;
+        trackEvent: import("@levelcode/common/types/contracts/analytics").TrackEventFn;
+        userId: string | undefined;
+        logger: import("@levelcode/common/types/contracts/logger").Logger;
     }) => Promise<{
         output: import("src").LevelCodeToolOutput<"send_message">;
     }>;
@@ -278,6 +291,9 @@ export declare const levelcodeToolHandlers: {
         previousToolCallFinished: Promise<void>;
         toolCall: import("@levelcode/common/tools/list").LevelCodeToolCall<"team_create">;
         agentStepId: string;
+        trackEvent: import("@levelcode/common/types/contracts/analytics").TrackEventFn;
+        userId: string | undefined;
+        logger: import("@levelcode/common/types/contracts/logger").Logger;
     }) => Promise<{
         output: import("src").LevelCodeToolOutput<"team_create">;
     }>;
@@ -285,6 +301,9 @@ export declare const levelcodeToolHandlers: {
         previousToolCallFinished: Promise<void>;
         toolCall: import("@levelcode/common/tools/list").LevelCodeToolCall<"team_delete">;
         agentStepId: string;
+        trackEvent: import("@levelcode/common/types/contracts/analytics").TrackEventFn;
+        userId: string | undefined;
+        logger: import("@levelcode/common/types/contracts/logger").Logger;
     }) => Promise<{
         output: import("src").LevelCodeToolOutput<"team_delete">;
     }>;

package/dist/packages/agent-runtime/src/tools/handlers/tool/send-message.d.ts

@@ -1,9 +1,14 @@
 import type { LevelCodeToolCall, LevelCodeToolOutput } from '@levelcode/common/tools/list';
+import type { TrackEventFn } from '@levelcode/common/types/contracts/analytics';
+import type { Logger } from '@levelcode/common/types/contracts/logger';
 type ToolName = 'send_message';
 export declare const handleSendMessage: (params: {
     previousToolCallFinished: Promise<void>;
     toolCall: LevelCodeToolCall<ToolName>;
     agentStepId: string;
+    trackEvent: TrackEventFn;
+    userId: string | undefined;
+    logger: Logger;
 }) => Promise<{
     output: LevelCodeToolOutput<ToolName>;
 }>;

package/dist/packages/agent-runtime/src/tools/handlers/tool/spawn-agent-utils.d.ts

@@ -6,6 +6,7 @@ import type { Logger } from '@levelcode/common/types/contracts/logger';
 import type { ParamsExcluding, OptionalFields } from '@levelcode/common/types/function-params';
 import type { PrintModeEvent } from '@levelcode/common/types/print-mode';
 import type { AgentState, AgentTemplateType, Subgoal } from '@levelcode/common/types/session-state';
+import type { TeamConfig, TeamRole } from '@levelcode/common/types/team-config';
 import type { ProjectFileContext } from '@levelcode/common/util/file';
 import type { ToolSet } from 'ai';
 /**
@@ -92,9 +93,38 @@ export interface TeamSpawnOptions {
     teamName: string;
     teamRole?: string;
 }
+/**
+ * Resolves a team_role to the corresponding agent template ID from agents/team/.
+ * For example, 'coordinator' maps to the coordinator agent template,
+ * 'manager' maps to the manager agent template, etc.
+ *
+ * Returns the agent template ID (which is the same as the role string for
+ * roles that have a dedicated template), or null if no template exists for
+ * the given role.
+ */
+export declare function resolveTeamRoleAgentType(teamRole: string): string | null;
+/**
+ * Validates that the spawning agent has authority to spawn an agent
+ * with the requested team role.
+ *
+ * Uses canManage from role-hierarchy to check that the spawner's role
+ * has a strictly higher authority level than the target role.
+ * Also checks getSpawnableRoles to ensure the specific role combination
+ * is allowed.
+ *
+ * @param spawnerRole - The team role of the agent performing the spawn
+ * @param targetRole - The team role being requested for the new agent
+ * @throws Error if the spawner lacks authority
+ */
+export declare function validateSpawnAuthority(spawnerRole: TeamRole, targetRole: TeamRole): void;
+/**
+ * Sends a notification to the team lead when a new agent joins the team.
+ * This is a fire-and-forget operation; errors are logged but not thrown.
+ */
+export declare function notifyTeamLead(teamName: string, teamConfig: TeamConfig, memberName: string, role: TeamRole, logger: Logger): Promise<void>;
 /**
  * Registers a spawned agent as a member of an existing team.
  * Returns the team context string to prepend to the agent's prompt,
  * or null if the team does not exist.
  */
-export declare function registerAgentAsTeamMember(agentId: string, agentType: string, options: TeamSpawnOptions, logger: Logger): string | null;
+export declare function registerAgentAsTeamMember(agentId: string, agentType: string, options: TeamSpawnOptions, logger: Logger): Promise<string | null>;

package/dist/packages/agent-runtime/src/tools/handlers/tool/spawn-agents.d.ts

@@ -1,4 +1,5 @@
 import { validateAndGetAgentTemplate, executeSubagent } from './spawn-agent-utils';
+import type { TrackEventFn } from '@levelcode/common/types/contracts/analytics';
 import type { LevelCodeToolCall, LevelCodeToolOutput } from '@levelcode/common/tools/list';
 import type { AgentTemplate } from '@levelcode/common/types/agent-template';
 import type { Logger } from '@levelcode/common/types/contracts/logger';
@@ -25,6 +26,7 @@ export declare const handleSpawnAgents: (params: {
     logger: Logger;
     system: string;
     tools?: ToolSet;
+    trackEvent: TrackEventFn;
     userId: string | undefined;
     userInputId: string;
     sendSubagentChunk: SendSubagentChunk;

package/dist/packages/agent-runtime/src/tools/handlers/tool/task-completed.d.ts

@@ -1,7 +1,15 @@
 import type { LevelCodeToolCall, LevelCodeToolOutput } from '@levelcode/common/tools/list';
-export declare const handleTaskCompleted: ({ previousToolCallFinished, }: {
+import type { TrackEventFn } from '@levelcode/common/types/contracts/analytics';
+import type { Logger } from '@levelcode/common/types/contracts/logger';
+export declare const handleTaskCompleted: ({ previousToolCallFinished, trackEvent, userId, logger, agentTemplate, }: {
     previousToolCallFinished: Promise<any>;
     toolCall: LevelCodeToolCall<"task_completed">;
+    trackEvent: TrackEventFn;
+    userId: string | undefined;
+    logger: Logger;
+    agentTemplate: {
+        name: string;
+    };
 }) => Promise<{
     output: LevelCodeToolOutput<"task_completed">;
 }>;

package/dist/packages/agent-runtime/src/tools/handlers/tool/task-update.d.ts

@@ -1,8 +1,13 @@
 import type { LevelCodeToolCall, LevelCodeToolOutput } from '@levelcode/common/tools/list';
+import type { TrackEventFn } from '@levelcode/common/types/contracts/analytics';
+import type { Logger } from '@levelcode/common/types/contracts/logger';
 type ToolName = 'task_update';
 export declare const handleTaskUpdate: (params: {
     previousToolCallFinished: Promise<void>;
     toolCall: LevelCodeToolCall<ToolName>;
+    trackEvent: TrackEventFn;
+    userId: string | undefined;
+    logger: Logger;
 }) => Promise<{
     output: LevelCodeToolOutput<ToolName>;
 }>;

package/dist/packages/agent-runtime/src/tools/handlers/tool/team-create.d.ts

@@ -1,9 +1,14 @@
 import type { LevelCodeToolCall, LevelCodeToolOutput } from '@levelcode/common/tools/list';
+import type { TrackEventFn } from '@levelcode/common/types/contracts/analytics';
+import type { Logger } from '@levelcode/common/types/contracts/logger';
 type ToolName = 'team_create';
 export declare const handleTeamCreate: (params: {
     previousToolCallFinished: Promise<void>;
     toolCall: LevelCodeToolCall<ToolName>;
     agentStepId: string;
+    trackEvent: TrackEventFn;
+    userId: string | undefined;
+    logger: Logger;
 }) => Promise<{
     output: LevelCodeToolOutput<ToolName>;
 }>;

package/dist/packages/agent-runtime/src/tools/handlers/tool/team-delete.d.ts

@@ -1,9 +1,14 @@
 import type { LevelCodeToolCall, LevelCodeToolOutput } from '@levelcode/common/tools/list';
+import type { TrackEventFn } from '@levelcode/common/types/contracts/analytics';
+import type { Logger } from '@levelcode/common/types/contracts/logger';
 type ToolName = 'team_delete';
 export declare const handleTeamDelete: (params: {
     previousToolCallFinished: Promise<void>;
     toolCall: LevelCodeToolCall<ToolName>;
     agentStepId: string;
+    trackEvent: TrackEventFn;
+    userId: string | undefined;
+    logger: Logger;
 }) => Promise<{
     output: LevelCodeToolOutput<ToolName>;
 }>;

package/dist/sdk/src/__tests__/team-api.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/src/client.d.ts

@@ -1,5 +1,8 @@
 import type { RunOptions, LevelCodeClientOptions } from './run';
 import type { RunState } from './run-state';
+import type { CreateTeamOptions, TeamStatus, RunWithTeamOptions } from './team';
+import type { TeamConfig } from '@levelcode/common/types/team-config';
+import type { TeamSummary } from '@levelcode/common/utils/team-discovery';
 export declare class LevelCodeClient {
     options: LevelCodeClientOptions & {
         apiKey: string;
@@ -30,4 +33,39 @@ export declare class LevelCodeClient {
      * @returns Promise that resolves to true if connected, false otherwise
      */
     checkConnection(): Promise<boolean>;
+    /**
+     * Create a new team for coordinating multiple agents.
+     *
+     * @param name - Unique name for the team.
+     * @param options - Optional configuration including description, phase, preset, members, and settings.
+     * @returns The created TeamConfig.
+     */
+    createTeam(name: string, options?: CreateTeamOptions): TeamConfig;
+    /**
+     * Delete a team and all its associated data (inboxes, tasks).
+     *
+     * @param name - Name of the team to delete.
+     */
+    deleteTeam(name: string): void;
+    /**
+     * Get the full status of a team including its config, tasks, and member count.
+     *
+     * @param name - Name of the team.
+     * @returns TeamStatus with config, tasks array, and memberCount.
+     */
+    getTeamStatus(name: string): TeamStatus;
+    /**
+     * List all teams with summary information (name, phase, member count).
+     *
+     * @returns Array of TeamSummary objects.
+     */
+    listTeams(): TeamSummary[];
+    /**
+     * Run an agent as part of a team. The agent will be registered as a team member
+     * and the run will include team context.
+     *
+     * @param options - Run options extended with teamName, memberName, and role.
+     * @returns A Promise that resolves to a RunState.
+     */
+    runWithTeam(options: RunWithTeamOptions): Promise<RunState>;
 }

package/dist/sdk/src/team.d.ts

@@ -0,0 +1,49 @@
+import type { TeamConfig, TeamMember, TeamTask, DevPhase, TeamRole } from '@levelcode/common/types/team-config';
+import type { TeamProtocolMessage } from '@levelcode/common/types/team-protocol';
+import type { TeamSummary } from '@levelcode/common/utils/team-discovery';
+import type { PresetConfig } from '@levelcode/common/utils/team-presets';
+import type { RunOptions, LevelCodeClientOptions } from './run';
+export type CreateTeamOptions = {
+    description?: string;
+    phase?: DevPhase;
+    preset?: string;
+    members?: Array<{
+        name: string;
+        role: TeamRole;
+        agentType: string;
+        model: string;
+        cwd?: string;
+    }>;
+    settings?: {
+        maxMembers?: number;
+        autoAssign?: boolean;
+    };
+};
+export type RunWithTeamOptions = RunOptions & LevelCodeClientOptions & {
+    teamName: string;
+    memberName: string;
+    role: TeamRole;
+};
+export type TeamStatus = {
+    config: TeamConfig;
+    tasks: TeamTask[];
+    memberCount: number;
+};
+/**
+ * Creates a new team with the given name and options.
+ * If a preset is specified, uses its member/settings defaults.
+ */
+export declare function sdkCreateTeam(name: string, leadAgentId: string, options?: CreateTeamOptions): TeamConfig;
+/**
+ * Deletes a team by name and removes all associated data.
+ */
+export declare function sdkDeleteTeam(name: string): void;
+/**
+ * Gets the full status of a team including config and tasks.
+ */
+export declare function sdkGetTeamStatus(name: string): TeamStatus;
+/**
+ * Lists all teams with summary information.
+ */
+export declare function sdkListTeams(): TeamSummary[];
+export type { TeamConfig, TeamMember, TeamTask, DevPhase, TeamRole, TeamProtocolMessage, TeamSummary, PresetConfig, };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@levelcode/sdk",
   "private": false,
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Official SDK for LevelCode — AI coding agent & framework",
   "license": "Apache-2.0",
   "type": "module",