novyx 2.12.0 → 3.2.0

package/dist/index.d.mts

@@ -623,13 +623,124 @@ declare class Novyx {
         reason?: string;
         approver_id?: string;
     }): Promise<Record<string, any>>;
-    listPolicies(): Promise<PoliciesResult>;
+    listPolicies(opts?: {
+        agent_id?: string;
+    }): Promise<PoliciesResult>;
+    /**
+     * Create or update a custom Control policy.
+     *
+     * Tier requirements:
+     * - draft_policies (Starter+) for any custom policy
+     * - agent_scoped_policies (Pro+) when agent_id is set
+     *
+     * @example
+     * await nx.createPolicy({
+     *   name: "pii_protection",
+     *   description: "Block PII exposure",
+     *   rules: [
+     *     {
+     *       match: "(ssn|social.security|passport)",
+     *       severity: "critical",
+     *       reason: "PII detected: {match}",
+     *     },
+     *   ],
+     *   whitelisted_domains: ["internal.company.com"],
+     * });
+     */
+    createPolicy(params: {
+        name: string;
+        rules: Array<Record<string, any>>;
+        description?: string;
+        step_types?: string[];
+        whitelisted_domains?: string[];
+        enabled?: boolean;
+        agent_id?: string;
+    }): Promise<Record<string, any>>;
+    /**
+     * Get a single policy by name and scope.
+     *
+     * The same policy name can exist at both tenant-wide (no agent_id) and
+     * agent-scoped levels independently. Specify which one you want.
+     */
+    getPolicy(policyName: string, opts?: {
+        agent_id?: string;
+    }): Promise<Record<string, any>>;
+    /**
+     * Update an existing custom policy. Increments version.
+     * agent_id targets the agent-scoped version; omit to update tenant-wide.
+     */
+    updatePolicy(policyName: string, params: {
+        rules: Array<Record<string, any>>;
+        description?: string;
+        step_types?: string[];
+        whitelisted_domains?: string[];
+        enabled?: boolean;
+        agent_id?: string;
+    }): Promise<Record<string, any>>;
+    /**
+     * Disable a custom policy (soft delete).
+     * Built-in policies cannot be deleted.
+     */
+    deletePolicy(policyName: string, opts?: {
+        agent_id?: string;
+    }): Promise<Record<string, any>>;
+    /**
+     * Aggregated governance stats over the audit chain.
+     *
+     * Returns totals (evaluations, executed, pending_review, approved, denied),
+     * violations broken down by policy and agent, and a time-series of activity.
+     *
+     * Tier: governance_dashboard feature (Starter+).
+     *
+     * @example
+     * const dash = await nx.governanceDashboard({ window: "7d" });
+     * console.log(dash.totals);
+     */
+    governanceDashboard(opts?: {
+        window?: "24h" | "7d" | "30d";
+        bucket?: "hour" | "day";
+    }): Promise<Record<string, any>>;
+    /**
+     * Per-agent violation history from the audit chain.
+     *
+     * Tier: governance_dashboard feature (Starter+).
+     */
+    agentViolations(agentId: string, opts?: {
+        limit?: number;
+        since?: string;
+        until?: string;
+    }): Promise<Record<string, any>>;
     explainAction(actionId: string): Promise<Record<string, any>>;
     streamStatus(): Promise<StreamStatusResult>;
     memoryHealth(): Promise<Record<string, any>>;
     private _controlRequest;
     /** Submit an action to Novyx Control for governed execution. */
+    /**
+     * Submit a governed action envelope to a separate Novyx Control instance.
+     * Legacy path. For the main Novyx Cloud governance flow, use `submitAction()`.
+     */
     actionSubmit(connector: string, operation: string, payload: Record<string, any>): Promise<any>;
+    /**
+     * Submit an action to the main Novyx Cloud governance flow.
+     *
+     * Evaluates against built-in + custom YAML policies (tenant-wide and
+     * optionally agent-scoped) via `POST /v1/actions` on the main API.
+     * Returns one of three statuses:
+     * - `"allowed"` — passed all policies
+     * - `"blocked"` — critical violation, action stopped
+     * - `"pending_review"` — high-severity violation routed to approval queue
+     *
+     * @example
+     * const result = await nx.submitAction("send_invoice", { amount: 50000 }, {
+     *   agent_id: "billing-bot",
+     * });
+     * if (result.status === "pending_review") {
+     *   console.log(`Awaiting approval: ${result.policy_result.action_id}`);
+     * }
+     */
+    submitAction(action: string, params?: Record<string, any>, opts?: {
+        agent_id?: string;
+    }): Promise<Record<string, any>>;
     /** Get the status of a Control action. */
     actionStatus(actionId: string): Promise<any>;
     /** List recent Control actions. */
@@ -640,10 +751,10 @@ declare class Novyx {
     policyCheck(): Promise<any>;
     createAgent(params: {
         name: string;
+        provider: "openai" | "anthropic" | "litellm";
+        model: string;
         agent_id?: string;
         description?: string;
-        model?: string;
-        provider?: string;
         instructions?: string;
         capabilities?: string[];
         memory_scope?: string;

package/dist/index.d.ts

@@ -623,13 +623,124 @@ declare class Novyx {
         reason?: string;
         approver_id?: string;
     }): Promise<Record<string, any>>;
-    listPolicies(): Promise<PoliciesResult>;
+    listPolicies(opts?: {
+        agent_id?: string;
+    }): Promise<PoliciesResult>;
+    /**
+     * Create or update a custom Control policy.
+     *
+     * Tier requirements:
+     * - draft_policies (Starter+) for any custom policy
+     * - agent_scoped_policies (Pro+) when agent_id is set
+     *
+     * @example
+     * await nx.createPolicy({
+     *   name: "pii_protection",
+     *   description: "Block PII exposure",
+     *   rules: [
+     *     {
+     *       match: "(ssn|social.security|passport)",
+     *       severity: "critical",
+     *       reason: "PII detected: {match}",
+     *     },
+     *   ],
+     *   whitelisted_domains: ["internal.company.com"],
+     * });
+     */
+    createPolicy(params: {
+        name: string;
+        rules: Array<Record<string, any>>;
+        description?: string;
+        step_types?: string[];
+        whitelisted_domains?: string[];
+        enabled?: boolean;
+        agent_id?: string;
+    }): Promise<Record<string, any>>;
+    /**
+     * Get a single policy by name and scope.
+     *
+     * The same policy name can exist at both tenant-wide (no agent_id) and
+     * agent-scoped levels independently. Specify which one you want.
+     */
+    getPolicy(policyName: string, opts?: {
+        agent_id?: string;
+    }): Promise<Record<string, any>>;
+    /**
+     * Update an existing custom policy. Increments version.
+     * agent_id targets the agent-scoped version; omit to update tenant-wide.
+     */
+    updatePolicy(policyName: string, params: {
+        rules: Array<Record<string, any>>;
+        description?: string;
+        step_types?: string[];
+        whitelisted_domains?: string[];
+        enabled?: boolean;
+        agent_id?: string;
+    }): Promise<Record<string, any>>;
+    /**
+     * Disable a custom policy (soft delete).
+     * Built-in policies cannot be deleted.
+     */
+    deletePolicy(policyName: string, opts?: {
+        agent_id?: string;
+    }): Promise<Record<string, any>>;
+    /**
+     * Aggregated governance stats over the audit chain.
+     *
+     * Returns totals (evaluations, executed, pending_review, approved, denied),
+     * violations broken down by policy and agent, and a time-series of activity.
+     *
+     * Tier: governance_dashboard feature (Starter+).
+     *
+     * @example
+     * const dash = await nx.governanceDashboard({ window: "7d" });
+     * console.log(dash.totals);
+     */
+    governanceDashboard(opts?: {
+        window?: "24h" | "7d" | "30d";
+        bucket?: "hour" | "day";
+    }): Promise<Record<string, any>>;
+    /**
+     * Per-agent violation history from the audit chain.
+     *
+     * Tier: governance_dashboard feature (Starter+).
+     */
+    agentViolations(agentId: string, opts?: {
+        limit?: number;
+        since?: string;
+        until?: string;
+    }): Promise<Record<string, any>>;
     explainAction(actionId: string): Promise<Record<string, any>>;
     streamStatus(): Promise<StreamStatusResult>;
     memoryHealth(): Promise<Record<string, any>>;
     private _controlRequest;
     /** Submit an action to Novyx Control for governed execution. */
+    /**
+     * Submit a governed action envelope to a separate Novyx Control instance.
+     * Legacy path. For the main Novyx Cloud governance flow, use `submitAction()`.
+     */
     actionSubmit(connector: string, operation: string, payload: Record<string, any>): Promise<any>;
+    /**
+     * Submit an action to the main Novyx Cloud governance flow.
+     *
+     * Evaluates against built-in + custom YAML policies (tenant-wide and
+     * optionally agent-scoped) via `POST /v1/actions` on the main API.
+     * Returns one of three statuses:
+     * - `"allowed"` — passed all policies
+     * - `"blocked"` — critical violation, action stopped
+     * - `"pending_review"` — high-severity violation routed to approval queue
+     *
+     * @example
+     * const result = await nx.submitAction("send_invoice", { amount: 50000 }, {
+     *   agent_id: "billing-bot",
+     * });
+     * if (result.status === "pending_review") {
+     *   console.log(`Awaiting approval: ${result.policy_result.action_id}`);
+     * }
+     */
+    submitAction(action: string, params?: Record<string, any>, opts?: {
+        agent_id?: string;
+    }): Promise<Record<string, any>>;
     /** Get the status of a Control action. */
     actionStatus(actionId: string): Promise<any>;
     /** List recent Control actions. */
@@ -640,10 +751,10 @@ declare class Novyx {
     policyCheck(): Promise<any>;
     createAgent(params: {
         name: string;
+        provider: "openai" | "anthropic" | "litellm";
+        model: string;
         agent_id?: string;
         description?: string;
-        model?: string;
-        provider?: string;
         instructions?: string;
         capabilities?: string[];
         memory_scope?: string;

package/dist/index.js

@@ -673,8 +673,129 @@ var Novyx = class {
     if (opts?.approver_id) params.approver_id = opts.approver_id;
     return this._request("POST", `/v1/approvals/${approvalId}/decision`, { params });
   }
-  async listPolicies() {
-    return this._request("GET", "/v1/control/policies");
+  // ========================================================================
+  // Novyx Control — Policy CRUD (Phase 1 + Phase 5)
+  // ========================================================================
+  async listPolicies(opts) {
+    const params = {};
+    if (opts?.agent_id) params.agent_id = opts.agent_id;
+    return this._request(
+      "GET",
+      "/v1/control/policies",
+      Object.keys(params).length > 0 ? { params } : void 0
+    );
+  }
+  /**
+   * Create or update a custom Control policy.
+   *
+   * Tier requirements:
+   * - draft_policies (Starter+) for any custom policy
+   * - agent_scoped_policies (Pro+) when agent_id is set
+   *
+   * @example
+   * await nx.createPolicy({
+   *   name: "pii_protection",
+   *   description: "Block PII exposure",
+   *   rules: [
+   *     {
+   *       match: "(ssn|social.security|passport)",
+   *       severity: "critical",
+   *       reason: "PII detected: {match}",
+   *     },
+   *   ],
+   *   whitelisted_domains: ["internal.company.com"],
+   * });
+   */
+  async createPolicy(params) {
+    const body = {
+      name: params.name,
+      description: params.description ?? "",
+      rules: params.rules,
+      enabled: params.enabled ?? true
+    };
+    if (params.step_types !== void 0) body.step_types = params.step_types;
+    if (params.whitelisted_domains !== void 0) body.whitelisted_domains = params.whitelisted_domains;
+    if (params.agent_id !== void 0) body.agent_id = params.agent_id;
+    return this._request("POST", "/v1/control/policies", { body });
+  }
+  /**
+   * Get a single policy by name and scope.
+   *
+   * The same policy name can exist at both tenant-wide (no agent_id) and
+   * agent-scoped levels independently. Specify which one you want.
+   */
+  async getPolicy(policyName, opts) {
+    const params = {};
+    if (opts?.agent_id) params.agent_id = opts.agent_id;
+    return this._request(
+      "GET",
+      `/v1/control/policies/${policyName}`,
+      Object.keys(params).length > 0 ? { params } : void 0
+    );
+  }
+  /**
+   * Update an existing custom policy. Increments version.
+   * agent_id targets the agent-scoped version; omit to update tenant-wide.
+   */
+  async updatePolicy(policyName, params) {
+    const body = {
+      name: policyName,
+      description: params.description ?? "",
+      rules: params.rules,
+      enabled: params.enabled ?? true
+    };
+    if (params.step_types !== void 0) body.step_types = params.step_types;
+    if (params.whitelisted_domains !== void 0) body.whitelisted_domains = params.whitelisted_domains;
+    if (params.agent_id !== void 0) body.agent_id = params.agent_id;
+    return this._request("PUT", `/v1/control/policies/${policyName}`, { body });
+  }
+  /**
+   * Disable a custom policy (soft delete).
+   * Built-in policies cannot be deleted.
+   */
+  async deletePolicy(policyName, opts) {
+    const params = {};
+    if (opts?.agent_id) params.agent_id = opts.agent_id;
+    return this._request(
+      "DELETE",
+      `/v1/control/policies/${policyName}`,
+      Object.keys(params).length > 0 ? { params } : void 0
+    );
+  }
+  // ========================================================================
+  // Novyx Control — Governance Dashboard (Phase 4)
+  // ========================================================================
+  /**
+   * Aggregated governance stats over the audit chain.
+   *
+   * Returns totals (evaluations, executed, pending_review, approved, denied),
+   * violations broken down by policy and agent, and a time-series of activity.
+   *
+   * Tier: governance_dashboard feature (Starter+).
+   *
+   * @example
+   * const dash = await nx.governanceDashboard({ window: "7d" });
+   * console.log(dash.totals);
+   */
+  async governanceDashboard(opts) {
+    const params = { window: opts?.window ?? "7d" };
+    if (opts?.bucket !== void 0) params.bucket = opts.bucket;
+    return this._request("GET", "/v1/control/dashboard", { params });
+  }
+  /**
+   * Per-agent violation history from the audit chain.
+   *
+   * Tier: governance_dashboard feature (Starter+).
+   */
+  async agentViolations(agentId, opts) {
+    const params = { limit: opts?.limit ?? 50 };
+    if (opts?.since !== void 0) params.since = opts.since;
+    if (opts?.until !== void 0) params.until = opts.until;
+    return this._request(
+      "GET",
+      `/v1/control/agents/${agentId}/violations`,
+      { params }
+    );
   }
   // ========================================================================
   // Explain Action
@@ -730,9 +851,36 @@ var Novyx = class {
     }
   }
   /** Submit an action to Novyx Control for governed execution. */
+  /**
+   * Submit a governed action envelope to a separate Novyx Control instance.
+   * Legacy path. For the main Novyx Cloud governance flow, use `submitAction()`.
+   */
   async actionSubmit(connector, operation, payload) {
     return this._controlRequest("POST", `/v1/actions/${connector}/${operation}`, { body: payload });
   }
+  /**
+   * Submit an action to the main Novyx Cloud governance flow.
+   *
+   * Evaluates against built-in + custom YAML policies (tenant-wide and
+   * optionally agent-scoped) via `POST /v1/actions` on the main API.
+   * Returns one of three statuses:
+   * - `"allowed"` — passed all policies
+   * - `"blocked"` — critical violation, action stopped
+   * - `"pending_review"` — high-severity violation routed to approval queue
+   *
+   * @example
+   * const result = await nx.submitAction("send_invoice", { amount: 50000 }, {
+   *   agent_id: "billing-bot",
+   * });
+   * if (result.status === "pending_review") {
+   *   console.log(`Awaiting approval: ${result.policy_result.action_id}`);
+   * }
+   */
+  async submitAction(action, params = {}, opts) {
+    const body = { action, params };
+    if (opts?.agent_id !== void 0) body.agent_id = opts.agent_id;
+    return this._request("POST", "/v1/actions", { body });
+  }
   /** Get the status of a Control action. */
   async actionStatus(actionId) {
     return this._controlRequest("GET", `/v1/actions/${actionId}`);
@@ -749,10 +897,19 @@ var Novyx = class {
   // Agents (Runtime v2)
   // ========================================================================
   async createAgent(params) {
+    const validProviders = ["openai", "anthropic", "litellm"];
+    if (!validProviders.includes(params.provider)) {
+      throw new Error(
+        `Unknown provider '${params.provider}'. Choose 'openai', 'anthropic', or 'litellm' (use litellm for Gemini, Mistral, Cohere, etc.).`
+      );
+    }
+    if (!params.model) {
+      throw new Error("model is required");
+    }
     const body = {
       name: params.name,
-      model: params.model ?? "gpt-4o-mini",
-      provider: params.provider ?? "openai"
+      model: params.model,
+      provider: params.provider
     };
     if (params.agent_id) body.agent_id = params.agent_id;
     if (params.description) body.description = params.description;

package/dist/index.mjs

@@ -640,8 +640,129 @@ var Novyx = class {
     if (opts?.approver_id) params.approver_id = opts.approver_id;
     return this._request("POST", `/v1/approvals/${approvalId}/decision`, { params });
   }
-  async listPolicies() {
-    return this._request("GET", "/v1/control/policies");
+  // ========================================================================
+  // Novyx Control — Policy CRUD (Phase 1 + Phase 5)
+  // ========================================================================
+  async listPolicies(opts) {
+    const params = {};
+    if (opts?.agent_id) params.agent_id = opts.agent_id;
+    return this._request(
+      "GET",
+      "/v1/control/policies",
+      Object.keys(params).length > 0 ? { params } : void 0
+    );
+  }
+  /**
+   * Create or update a custom Control policy.
+   *
+   * Tier requirements:
+   * - draft_policies (Starter+) for any custom policy
+   * - agent_scoped_policies (Pro+) when agent_id is set
+   *
+   * @example
+   * await nx.createPolicy({
+   *   name: "pii_protection",
+   *   description: "Block PII exposure",
+   *   rules: [
+   *     {
+   *       match: "(ssn|social.security|passport)",
+   *       severity: "critical",
+   *       reason: "PII detected: {match}",
+   *     },
+   *   ],
+   *   whitelisted_domains: ["internal.company.com"],
+   * });
+   */
+  async createPolicy(params) {
+    const body = {
+      name: params.name,
+      description: params.description ?? "",
+      rules: params.rules,
+      enabled: params.enabled ?? true
+    };
+    if (params.step_types !== void 0) body.step_types = params.step_types;
+    if (params.whitelisted_domains !== void 0) body.whitelisted_domains = params.whitelisted_domains;
+    if (params.agent_id !== void 0) body.agent_id = params.agent_id;
+    return this._request("POST", "/v1/control/policies", { body });
+  }
+  /**
+   * Get a single policy by name and scope.
+   *
+   * The same policy name can exist at both tenant-wide (no agent_id) and
+   * agent-scoped levels independently. Specify which one you want.
+   */
+  async getPolicy(policyName, opts) {
+    const params = {};
+    if (opts?.agent_id) params.agent_id = opts.agent_id;
+    return this._request(
+      "GET",
+      `/v1/control/policies/${policyName}`,
+      Object.keys(params).length > 0 ? { params } : void 0
+    );
+  }
+  /**
+   * Update an existing custom policy. Increments version.
+   * agent_id targets the agent-scoped version; omit to update tenant-wide.
+   */
+  async updatePolicy(policyName, params) {
+    const body = {
+      name: policyName,
+      description: params.description ?? "",
+      rules: params.rules,
+      enabled: params.enabled ?? true
+    };
+    if (params.step_types !== void 0) body.step_types = params.step_types;
+    if (params.whitelisted_domains !== void 0) body.whitelisted_domains = params.whitelisted_domains;
+    if (params.agent_id !== void 0) body.agent_id = params.agent_id;
+    return this._request("PUT", `/v1/control/policies/${policyName}`, { body });
+  }
+  /**
+   * Disable a custom policy (soft delete).
+   * Built-in policies cannot be deleted.
+   */
+  async deletePolicy(policyName, opts) {
+    const params = {};
+    if (opts?.agent_id) params.agent_id = opts.agent_id;
+    return this._request(
+      "DELETE",
+      `/v1/control/policies/${policyName}`,
+      Object.keys(params).length > 0 ? { params } : void 0
+    );
+  }
+  // ========================================================================
+  // Novyx Control — Governance Dashboard (Phase 4)
+  // ========================================================================
+  /**
+   * Aggregated governance stats over the audit chain.
+   *
+   * Returns totals (evaluations, executed, pending_review, approved, denied),
+   * violations broken down by policy and agent, and a time-series of activity.
+   *
+   * Tier: governance_dashboard feature (Starter+).
+   *
+   * @example
+   * const dash = await nx.governanceDashboard({ window: "7d" });
+   * console.log(dash.totals);
+   */
+  async governanceDashboard(opts) {
+    const params = { window: opts?.window ?? "7d" };
+    if (opts?.bucket !== void 0) params.bucket = opts.bucket;
+    return this._request("GET", "/v1/control/dashboard", { params });
+  }
+  /**
+   * Per-agent violation history from the audit chain.
+   *
+   * Tier: governance_dashboard feature (Starter+).
+   */
+  async agentViolations(agentId, opts) {
+    const params = { limit: opts?.limit ?? 50 };
+    if (opts?.since !== void 0) params.since = opts.since;
+    if (opts?.until !== void 0) params.until = opts.until;
+    return this._request(
+      "GET",
+      `/v1/control/agents/${agentId}/violations`,
+      { params }
+    );
   }
   // ========================================================================
   // Explain Action
@@ -697,9 +818,36 @@ var Novyx = class {
     }
   }
   /** Submit an action to Novyx Control for governed execution. */
+  /**
+   * Submit a governed action envelope to a separate Novyx Control instance.
+   * Legacy path. For the main Novyx Cloud governance flow, use `submitAction()`.
+   */
   async actionSubmit(connector, operation, payload) {
     return this._controlRequest("POST", `/v1/actions/${connector}/${operation}`, { body: payload });
   }
+  /**
+   * Submit an action to the main Novyx Cloud governance flow.
+   *
+   * Evaluates against built-in + custom YAML policies (tenant-wide and
+   * optionally agent-scoped) via `POST /v1/actions` on the main API.
+   * Returns one of three statuses:
+   * - `"allowed"` — passed all policies
+   * - `"blocked"` — critical violation, action stopped
+   * - `"pending_review"` — high-severity violation routed to approval queue
+   *
+   * @example
+   * const result = await nx.submitAction("send_invoice", { amount: 50000 }, {
+   *   agent_id: "billing-bot",
+   * });
+   * if (result.status === "pending_review") {
+   *   console.log(`Awaiting approval: ${result.policy_result.action_id}`);
+   * }
+   */
+  async submitAction(action, params = {}, opts) {
+    const body = { action, params };
+    if (opts?.agent_id !== void 0) body.agent_id = opts.agent_id;
+    return this._request("POST", "/v1/actions", { body });
+  }
   /** Get the status of a Control action. */
   async actionStatus(actionId) {
     return this._controlRequest("GET", `/v1/actions/${actionId}`);
@@ -716,10 +864,19 @@ var Novyx = class {
   // Agents (Runtime v2)
   // ========================================================================
   async createAgent(params) {
+    const validProviders = ["openai", "anthropic", "litellm"];
+    if (!validProviders.includes(params.provider)) {
+      throw new Error(
+        `Unknown provider '${params.provider}'. Choose 'openai', 'anthropic', or 'litellm' (use litellm for Gemini, Mistral, Cohere, etc.).`
+      );
+    }
+    if (!params.model) {
+      throw new Error("model is required");
+    }
     const body = {
       name: params.name,
-      model: params.model ?? "gpt-4o-mini",
-      provider: params.provider ?? "openai"
+      model: params.model,
+      provider: params.provider
     };
     if (params.agent_id) body.agent_id = params.agent_id;
     if (params.description) body.description = params.description;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "novyx",
-  "version": "2.12.0",
+  "version": "3.2.0",
   "description": "Novyx SDK - Persistent memory, rollback, and audit trail for AI agents",
   "main": "dist/index.js",
   "module": "dist/index.mjs",