feat(agent): add agent command group with session and state management

Author: chenanran555

packages/cli/src/commands.ts

@@ -83,6 +83,22 @@ import {
   pluginLink,
   pluginList,
   pluginRemove,
+  agentInit,
+  agentValidate,
+  agentPlan,
+  agentApply,
+  agentDestroy,
+  agentStateList,
+  agentStateShow,
+  agentStateRm,
+  agentStateImport,
+  agentSessionCreate,
+  agentSessionList,
+  agentSessionGet,
+  agentSessionDelete,
+  agentSessionRun,
+  agentSessionSend,
+  agentSessionEvents,
 } from "bailian-cli-commands";
 
 // Full bailian-cli product: every command, exposed under the `bl` binary.
@@ -174,4 +190,20 @@ export const commands: Record<string, AnyCommand> = {
   "plugin link": pluginLink,
   "plugin list": pluginList,
   "plugin remove": pluginRemove,
+  "agent init": agentInit,
+  "agent validate": agentValidate,
+  "agent plan": agentPlan,
+  "agent apply": agentApply,
+  "agent destroy": agentDestroy,
+  "agent state list": agentStateList,
+  "agent state show": agentStateShow,
+  "agent state rm": agentStateRm,
+  "agent state import": agentStateImport,
+  "agent session create": agentSessionCreate,
+  "agent session list": agentSessionList,
+  "agent session get": agentSessionGet,
+  "agent session delete": agentSessionDelete,
+  "agent session run": agentSessionRun,
+  "agent session send": agentSessionSend,
+  "agent session events": agentSessionEvents,
 };

packages/commands/package.json

@@ -40,6 +40,7 @@
     "check": "vp check"
   },
   "dependencies": {
+    "@openagentpack/sdk": "0.1.0",
     "bailian-cli-core": "workspace:*",
     "bailian-cli-runtime": "workspace:*",
     "boxen": "catalog:",

packages/commands/src/commands/agent/_engine/address-utils.ts

@@ -0,0 +1,11 @@
+import type { ResourceAddress } from "@openagentpack/sdk";
+
+/** Full state address: provider.type.name */
+export function formatResourceAddress(address: ResourceAddress): string {
+  return `${address.provider}.${address.type}.${address.name}`;
+}
+
+/** CLI display short label: type.name (provider) */
+export function formatResourceLabel(address: ResourceAddress): string {
+  return `${address.type}.${address.name} (${address.provider})`;
+}

packages/commands/src/commands/agent/_engine/config-loader.ts

@@ -0,0 +1,43 @@
+import {
+  createProjectRuntime,
+  type ProjectRuntimeContext,
+  resolveProjectConfig,
+  UserError,
+} from "@openagentpack/sdk";
+import { ensureCredentials } from "./credentials.ts";
+import { loadFileState } from "./file-state-manager.ts";
+
+/**
+ * Build a full ProjectRuntimeContext from a config file path — the standard
+ * entry point for agent commands that need the SDK engine. Mirrors OpenAgentPack
+ * CLI's buildCliRuntime: resolve config → load local state → assemble runtime.
+ */
+export async function buildAgentRuntime(
+  filePath: string,
+  options: { resolveEnv?: boolean; projectName?: string; statePath?: string } = {},
+): Promise<ProjectRuntimeContext & { configPath: string }> {
+  ensureCredentials();
+  const { config, configPath, projectName } = await resolveProjectConfig(filePath, options);
+  const state = await loadFileState(configPath, options.statePath, projectName);
+  const ctx = createProjectRuntime({
+    projectName,
+    config,
+    state,
+    configPath,
+    providers: config.providers,
+  });
+  return { ...ctx, configPath };
+}
+
+/** Ensure a user-supplied --provider value is actually configured in agents.yaml. */
+export function assertProviderConfigured(
+  ctx: ProjectRuntimeContext,
+  provider: string | undefined,
+): void {
+  if (!provider || provider === "all") return;
+  if (ctx.providers.has(provider)) return;
+  const available = Array.from(ctx.providers.keys()).join(", ") || "none";
+  throw new UserError(
+    `Provider '${provider}' is not configured. Available providers: ${available}.`,
+  );
+}

packages/commands/src/commands/agent/_engine/console-capture.ts

@@ -0,0 +1,23 @@
+/**
+ * Redirect `console.log` / `console.info` to stderr while `fn` runs.
+ *
+ * The OpenAgentPack SDK's provider adapters emit progress/debug logging via
+ * `console.log` (e.g. `[skill-upload]`), which would corrupt bl's stdout data
+ * channel in `--output json` mode. Wrapping SDK calls that may log keeps stdout
+ * a clean data channel. Restores the originals on completion.
+ */
+export async function withStdoutProtected<T>(fn: () => Promise<T>): Promise<T> {
+  const originalLog = console.log;
+  const originalInfo = console.info;
+  const toStderr = (...args: unknown[]): void => {
+    process.stderr.write(`${args.map((arg) => String(arg)).join(" ")}\n`);
+  };
+  console.log = toStderr;
+  console.info = toStderr;
+  try {
+    return await fn();
+  } finally {
+    console.log = originalLog;
+    console.info = originalInfo;
+  }
+}

packages/commands/src/commands/agent/_engine/credentials.ts

@@ -0,0 +1,18 @@
+import { bootstrapRuntimeCredentialsSync } from "@openagentpack/sdk";
+
+let bootstrapped = false;
+
+/**
+ * Lazily load `.env` and `~/.agents/config.json` into `process.env` so the
+ * OpenAgentPack SDK can resolve provider credentials (e.g. DASHSCOPE_API_KEY,
+ * BAILIAN_WORKSPACE_ID). Safe to call repeatedly — only the first call does I/O.
+ *
+ * NOTE: agent commands declare `auth: "none"` and let the SDK own credential
+ * resolution. This is the documented tradeoff of the wholesale SDK integration;
+ * bl's own `--api-key` / `bl auth login` flow is bridged separately as a follow-up.
+ */
+export function ensureCredentials(): void {
+  if (bootstrapped) return;
+  bootstrapped = true;
+  bootstrapRuntimeCredentialsSync();
+}

packages/commands/src/commands/agent/_engine/errors.ts

@@ -0,0 +1,19 @@
+import { UserError } from "@openagentpack/sdk";
+import { BailianError, ExitCode } from "bailian-cli-core";
+
+/**
+ * Run an SDK-backed operation, translating SDK error types into BailianError so
+ * bl's error handler produces the right exit code and hint formatting.
+ * SDK `UserError` → USAGE/GENERAL; any other Error → GENERAL (message passed
+ * through, per bl's "don't translate server errors" boundary).
+ */
+export async function withAgentErrors<T>(fn: () => Promise<T>): Promise<T> {
+  try {
+    return await fn();
+  } catch (error) {
+    if (error instanceof BailianError) throw error;
+    if (error instanceof UserError) throw new BailianError(error.message, ExitCode.USAGE);
+    if (error instanceof Error) throw new BailianError(error.message, ExitCode.GENERAL);
+    throw error;
+  }
+}

packages/commands/src/commands/agent/_engine/feedback.ts

@@ -0,0 +1,10 @@
+import type { RuntimeFeedbackEvent } from "@openagentpack/sdk";
+
+/**
+ * Render SDK runtime feedback to stderr, keeping stdout a clean data channel.
+ * Used as the `onFeedback` sink for plan/apply so progress messages don't mix
+ * with structured output.
+ */
+export function renderAgentFeedback(event: RuntimeFeedbackEvent): void {
+  process.stderr.write(`${event.message}\n`);
+}

packages/commands/src/commands/agent/_engine/file-state-manager.ts

@@ -0,0 +1,24 @@
+import { basename, dirname, resolve } from "node:path";
+import {
+  type IStateManager,
+  LocalFileStateBackend,
+  StateManager,
+  type StateScope,
+} from "@openagentpack/sdk";
+
+function createStateScope(configPath: string, projectName?: string): StateScope {
+  const resolved = resolve(configPath);
+  return { projectId: projectName ?? basename(dirname(resolved)) };
+}
+
+/** Load or initialize a file-based StateManager (mirrors OpenAgentPack CLI). */
+export async function loadFileState(
+  configPath: string,
+  statePath?: string,
+  projectName?: string,
+): Promise<IStateManager> {
+  const resolved = resolve(configPath);
+  const backend = new LocalFileStateBackend({ configPath: resolved, statePath });
+  const path = backend.getStatePath(createStateScope(resolved, projectName));
+  return StateManager.load(path);
+}

packages/commands/src/commands/agent/_engine/pagination.ts

@@ -0,0 +1,25 @@
+export interface PagedResult<T> {
+  items: T[];
+  hasMore: boolean;
+  nextPage?: string;
+}
+
+/** Fetch the first page, then follow cursors while `all` is true. */
+export async function fetchAllPages<T>(
+  fetchPage: (page?: string) => Promise<PagedResult<T>>,
+  all?: boolean,
+): Promise<PagedResult<T>> {
+  const first = await fetchPage();
+  const items = [...first.items];
+  let hasMore = first.hasMore;
+  let nextPage = first.nextPage;
+
+  while (all && nextPage) {
+    const next = await fetchPage(nextPage);
+    items.push(...next.items);
+    hasMore = next.hasMore;
+    nextPage = next.nextPage;
+  }
+
+  return { items, hasMore, nextPage };
+}