@kadi.build/core 0.8.0 → 0.11.0

package/src/client.ts

@@ -59,6 +59,8 @@ import { resolveAbilityEntry, resolveAbilityScript } from './lockfile.js';
 import { loadNativeTransport } from './transports/native.js';
 import { loadStdioTransport } from './transports/stdio.js';
 import { loadBrokerTransport } from './transports/broker.js';
+import { AgentJsonManager } from './agent-json.js';
+import { ProcessManager } from './process-manager.js';
 
 // ═══════════════════════════════════════════════════════════════
 // CONSTANTS
@@ -204,6 +206,12 @@ export class KadiClient {
   /** Registered disconnect hooks */
   private readonly disconnectHooks: Array<() => Promise<void>> = [];
 
+  /** Lazy-initialized AgentJsonManager */
+  private _agentJson: AgentJsonManager | null = null;
+
+  /** Lazy-initialized ProcessManager */
+  private _processes: ProcessManager | null = null;
+
   // ─────────────────────────────────────────────────────────────
   // IDENTITY (single keypair shared across all broker connections)
   // ─────────────────────────────────────────────────────────────
@@ -1823,8 +1831,12 @@ export class KadiClient {
    *   output: z.object({ result: z.number() }),
    * }, async ({ a, b }) => ({ result: a + b }));
    *
-   * // Register only on specific broker
-   * client.registerTool(def, handler, { brokers: ['internal'] });
+   * // Register on specific brokers with per-broker networks
+   * client.registerTool(def, handler, {
+   *   brokers: {
+   *     internal: { networks: ['private'] },
+   *   },
+   * });
    * ```
    */
   registerTool<TInput, TOutput>(
@@ -1850,21 +1862,36 @@ export class KadiClient {
         : undefined,
     };
 
-    // Validate per-tool networks against broker networks (skip when no brokers)
-    const targetNetworks = options.networks ?? [];
-    if (targetNetworks.length > 0 && Object.keys(this.config.brokers).length > 0) {
-      const allNetworks = this.getAllConfiguredNetworks();
-      const invalid = targetNetworks.filter((n) => !allNetworks.includes(n));
-      if (invalid.length > 0) {
-        throw new KadiError(
-          `Tool "${definition.name}" has networks ${JSON.stringify(invalid)} not present in client networks ${JSON.stringify(allNetworks)}. Per-tool networks must be a subset of the client's networks — a tool can only be visible on networks the agent has joined.`,
-          'INVALID_CONFIG',
-          {
-            toolName: definition.name,
-            invalidNetworks: invalid,
-            clientNetworks: allNetworks,
-          }
-        );
+    // Validate per-broker network scoping (skip when no brokers configured)
+    const brokerScopes = options.brokers ?? {};
+    if (Object.keys(brokerScopes).length > 0 && Object.keys(this.config.brokers).length > 0) {
+      for (const [brokerName, scope] of Object.entries(brokerScopes)) {
+        const brokerConfig = this.config.brokers[brokerName];
+        if (!brokerConfig) {
+          throw new KadiError(
+            `Tool "${definition.name}" references broker "${brokerName}" which is not configured. Available brokers: ${JSON.stringify(Object.keys(this.config.brokers))}`,
+            'INVALID_CONFIG',
+            {
+              toolName: definition.name,
+              broker: brokerName,
+              availableBrokers: Object.keys(this.config.brokers),
+            }
+          );
+        }
+        const brokerNetworks = brokerConfig.networks;
+        const invalid = scope.networks.filter((n) => !brokerNetworks.includes(n));
+        if (invalid.length > 0) {
+          throw new KadiError(
+            `Tool "${definition.name}" has networks ${JSON.stringify(invalid)} not present on broker "${brokerName}" networks ${JSON.stringify(brokerNetworks)}. Per-tool networks must be a subset of the broker's networks — a tool can only be visible on networks the agent has joined.`,
+            'INVALID_CONFIG',
+            {
+              toolName: definition.name,
+              broker: brokerName,
+              invalidNetworks: invalid,
+              brokerNetworks,
+            }
+          );
+        }
       }
     }
 
@@ -1872,46 +1899,45 @@ export class KadiClient {
     const registered: RegisteredTool = {
       definition: jsonDefinition,
       handler: handler as ToolHandler,
-      targetBrokers: options.brokers ?? [],
-      targetNetworks,
+      brokerNetworks: brokerScopes,
     };
     this.tools.set(definition.name, registered);
   }
 
-  /**
-   * Get the union of all networks configured across all brokers.
-   * Used by registerTool() to validate per-tool network targeting.
-   */
-  private getAllConfiguredNetworks(): string[] {
-    const all = new Set<string>();
-    for (const broker of Object.values(this.config.brokers)) {
-      for (const n of broker.networks) all.add(n);
-    }
-    return [...all];
-  }
-
   /**
    * Get tool definitions, optionally filtered for a specific broker.
    *
    * @param forBroker - If provided, only return tools targeted for this broker.
-   *                    Tools with empty targetBrokers are included for all brokers.
+   *                    Tools with empty brokerNetworks are included for all brokers.
    */
   private getToolDefinitions(forBroker?: string): BrokerToolDefinition[] {
-    return Array.from(this.tools.values())
-      .filter((t) => {
-        // If no broker specified, return all tools (e.g., for readAgentJson)
-        if (!forBroker) return true;
-
-        // Empty targetBrokers means "register with all brokers"
-        if (t.targetBrokers.length === 0) return true;
-
-        // Otherwise, only include if this broker is in the target list
-        return t.targetBrokers.includes(forBroker);
-      })
-      .map((t) => ({
+    const results: BrokerToolDefinition[] = [];
+
+    for (const t of this.tools.values()) {
+      const hasBrokerNetworks = Object.keys(t.brokerNetworks).length > 0;
+
+      if (!forBroker) {
+        // No broker filter — return all tools (e.g., for readAgentJson)
+        results.push({ ...t.definition });
+        continue;
+      }
+
+      if (!hasBrokerNetworks) {
+        // Empty brokerNetworks = register with all brokers, no network field
+        results.push({ ...t.definition });
+        continue;
+      }
+
+      const scope = t.brokerNetworks[forBroker];
+      if (!scope) continue; // Tool not registered on this broker
+
+      results.push({
         ...t.definition,
-        ...(t.targetNetworks.length > 0 && { networks: t.targetNetworks }),
-      }));
+        ...(scope.networks.length > 0 && { networks: scope.networks }),
+      });
+    }
+
+    return results;
   }
 
   /**
@@ -2391,6 +2417,54 @@ export class KadiClient {
     await new Promise(() => {});
   }
 
+  // ─────────────────────────────────────────────────────────────
+  // AGENT JSON MANAGER
+  // ─────────────────────────────────────────────────────────────
+
+  /**
+   * Access the AgentJsonManager for reading/writing agent.json files.
+   *
+   * Lazily created on first access. Provides unified API for project root,
+   * installed ability, and KADI home agent.json files.
+   *
+   * @example
+   * ```typescript
+   * const config = await client.agentJson.readProject();
+   * const deploy = await client.agentJson.readProject('deploy.local');
+   * await client.agentJson.writeProject('deploy.staging', { target: 'akash' });
+   * ```
+   */
+  get agentJson(): AgentJsonManager {
+    if (!this._agentJson) {
+      this._agentJson = new AgentJsonManager();
+    }
+    return this._agentJson;
+  }
+
+  // ─────────────────────────────────────────────────────────────
+  // PROCESS MANAGER
+  // ─────────────────────────────────────────────────────────────
+
+  /**
+   * Access the ProcessManager for spawning and managing background processes.
+   *
+   * Lazily created on first access. Supports headless, piped, and bridge modes.
+   *
+   * @example
+   * ```typescript
+   * const build = await client.processes.spawn('build', {
+   *   command: 'docker', args: ['build', '.'], mode: 'piped',
+   * });
+   * build.on('exit', ({ exitCode }) => console.log('done:', exitCode));
+   * ```
+   */
+  get processes(): ProcessManager {
+    if (!this._processes) {
+      this._processes = new ProcessManager();
+    }
+    return this._processes;
+  }
+
   // ─────────────────────────────────────────────────────────────
   // UTILITY
   // ─────────────────────────────────────────────────────────────

package/src/errors.ts

@@ -65,6 +65,21 @@ export type ErrorCode =
   | 'INVALID_INPUT'
   | 'PROJECT_ROOT_NOT_FOUND'
 
+  // Agent.json errors
+  | 'AGENT_JSON_NOT_FOUND'
+  | 'AGENT_JSON_PARSE_ERROR'
+  | 'AGENT_JSON_WRITE_ERROR'
+  | 'AGENT_JSON_FIELD_NOT_FOUND'
+  | 'AGENT_JSON_VERSION_AMBIGUOUS'
+
+  // Process manager errors
+  | 'PROCESS_ALREADY_EXISTS'
+  | 'PROCESS_NOT_FOUND'
+  | 'PROCESS_NOT_RUNNING'
+  | 'PROCESS_BRIDGE_ERROR'
+  | 'PROCESS_SPAWN_FAILED'
+  | 'PROCESS_TIMEOUT'
+
   // Transport errors
   | 'STDIO_ERROR'
   | 'STDIO_PROCESS_FAILED'

package/src/index.ts

@@ -91,8 +91,40 @@ export type {
 
   // Script resolution
   ResolvedScript,
+
+  // Agent.json types
+  AgentJson,
+  AgentJsonScripts,
+  AgentJsonBuildProfile,
+  AgentJsonDeployProfile,
+  AgentJsonManagerOptions,
+  ReadAbilityOptions,
+  AbilityInfo,
+  AgentJsonPaths,
+
+  // Process manager types
+  ProcessMode,
+  ProcessState,
+  SpawnOptions,
+  ProcessInfo,
+  ProcessExitInfo,
+  ProcessOutput,
+  ProcessListOptions,
+  ProcessPruneOptions,
 } from './types.js';
 
+// Agent.json manager
+export { AgentJsonManager } from './agent-json.js';
+
+// Process manager
+export { ProcessManager, ManagedProcess } from './process-manager.js';
+
+// Dot-path utilities
+export { getByPath, setByPath, deleteByPath, deepMerge } from './utils.js';
+
+// Stdio framing (for advanced use cases — building custom bridge protocols)
+export { StdioMessageReader, StdioMessageWriter } from './stdio-framing.js';
+
 // Zod utilities
 export { zodToJsonSchema, isZodSchema } from './zod.js';