feat(ENG-130): add defender config option to StackOneToolSet

[hiskudin]

Summary

Adds a defender option to StackOneToolSet for explicit per-toolset control over prompt injection detection on every tool call. By default the SDK defers to the project dashboard setting and adds no defender_config to the payload; passing an explicit value lets a single toolset opt in, opt out, or override the dashboard.

• Fixes a silent bug where defender_enabled was dropped by Zod validation before reaching the RPC call
• Extends the RPC schema to forward defender_config per-request (backend changes for the new sub-fields tracked separately)
• Field names match canonical DefenderSettings from @stackone/core

Current setup

defender option	Wire payload sent	Effective behavior
omitted	defender_config omitted	Same as below (normalized to { useProjectSettings: true })
{ useProjectSettings: true } (default)	defender_config omitted	Project dashboard setting controls — SDK adds nothing
{ enabled, blockHighRisk, ... }	defender_config: { ...mapped }	SDK-level config wins, overrides the dashboard
null	defender_config: { enabled: false, ... all false }	Defender forcibly disabled, overrides the dashboard

When passing an explicit object, missing fields fall back to DEFAULT_DEFENDER_CONFIG (re-exported from @stackone/ai).

Default behavior (omit defender)

const toolset = new StackOneToolSet({ apiKey: '...' });
// → SDK adds nothing to the RPC payload; project dashboard controls

Disable entirely

const toolset = new StackOneToolSet({ apiKey: '...', defender: null });
// → SDK sends defender_config with all fields false, overriding the dashboard

Defer to project dashboard (explicit form)

const toolset = new StackOneToolSet({
  apiKey: '...',
  defender: { useProjectSettings: true },
});
// Combining with other fields throws ToolSetConfigError at construction

Explicit SDK-level config

import { StackOneToolSet, DEFAULT_DEFENDER_CONFIG } from '@stackone/ai';

// Opt in with safe defaults, but block on HIGH/CRITICAL
const toolset = new StackOneToolSet({
  apiKey: '...',
  defender: { ...DEFAULT_DEFENDER_CONFIG, blockHighRisk: true },
});

// Fully explicit
const toolset = new StackOneToolSet({
  apiKey: '...',
  defender: {
    enabled: true,
    blockHighRisk: true,          // block HIGH/CRITICAL instead of just annotating
    useTier1Classification: true, // pattern-based detection
    useTier2Classification: true, // ML-based detection (requires onnxruntime-node)
  },
});

Per-field fallbacks (DEFAULT_DEFENDER_CONFIG)

These apply only when an explicit defender config object is passed with some fields omitted. They do NOT apply when defender is omitted entirely.

Field	Fallback	Description
enabled	true	Master switch. false disables scanning for this toolset.
blockHighRisk	false	Block tool calls with HIGH/CRITICAL risk. When false, risky content is annotated but still returned.
useTier1Classification	true	Fast pattern-based detection (regex rules for role markers, instruction overrides, etc.).
useTier2Classification	true	ML-based detection (ONNX model). Catches novel attacks patterns miss. Requires onnxruntime-node at runtime.

Changes

• src/types.ts — DefenderConfig is a discriminated union ({ useProjectSettings: true } | explicit-object); DEFAULT_DEFENDER_CONFIG kept as a public reference users can spread
• src/schema.ts — adds defender_config to rpcActionRequestSchema
• src/rpc-client.ts — forwards defender_config in request body when present
• src/toolsets.ts — resolves defender config at construction (omitted → normalized to { useProjectSettings: true }), validates useProjectSettings exclusivity, computes wire payload once via buildDefenderFields
• src/index.ts — re-exports DEFAULT_DEFENDER_CONFIG

Notes

The sub-fields under defender_config (block_high_risk, use_tier1_classification, use_tier2_classification) are forwarded in the RPC payload but require a backend change to ActionsRpcRequestDto to take full effect. That work is tracked separately.

🤖 Generated with Claude Code

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/StackOneHQ/stackone-ai-node/@stackone/ai@328

commit: 1c6324d

[cubic-dev-ai]

1 issue found across 5 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/toolsets.ts">

<violation number="1" location="src/toolsets.ts:979">
P2: `dryRun` request serialization is now inconsistent with real RPC calls because `defender_enabled` is forwarded only in the live path.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[Copilot]

Pull request overview

Adds a toolset-level defender configuration to StackOneToolSet so consumers can control prompt-injection detection behavior (currently via per-request defender_enabled), and fixes a silent validation issue where defender_enabled was previously dropped before reaching the RPC call.

Changes:

• Introduces DefenderConfig and exports it from the public entrypoint.
• Extends the RPC request Zod schema to accept defender_enabled and forwards it in the RPC client request payload.
• Adds defender to StackOneToolSet config and threads defender.enabled → defender_enabled into RPC calls.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/types.ts	Adds DefenderConfig interface describing toolset-level defender settings.
src/toolsets.ts	Accepts/stores defender config on the toolset and injects defender_enabled into RPC calls.
src/schema.ts	Updates rpcActionRequestSchema to validate defender_enabled so it isn’t stripped.
src/rpc-client.ts	Includes validated defender_enabled in the JSON payload sent to /actions/rpc.
src/index.ts	Re-exports DefenderConfig for SDK consumers.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[cubic-dev-ai]

3 issues found across 5 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/toolsets.ts">

<violation number="1" location="src/toolsets.ts:995">
P2: `dryRun` no longer matches the real RPC payload for defender settings.</violation>
</file>

<file name="src/rpc-client.ts">

<violation number="1" location="src/rpc-client.ts:56">
P1: Don't forward the unsupported defender tuning fields yet. Only `defender_enabled` is wired through the RPC API today, so sending the other three keys can break RPC calls until the backend DTO is updated.</violation>
</file>

<file name="src/types.ts">

<violation number="1" location="src/types.ts:271">
P1: Defaulting omitted `defender` to an explicit config overrides existing project settings for every RPC call.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

No issues found across 8 files

[glebedel]

@hiskudin you now have merge conflicts

[Copilot]

Pull request overview

Adds a defender configuration option to StackOneToolSet so SDK consumers can explicitly control prompt-injection scanning behavior (default on, project settings, or fully disabled) and forwards the resolved settings through the RPC request payload.

Changes:

• Introduces DefenderConfig and DEFAULT_DEFENDER_CONFIG defaults for SDK-level defender behavior.
• Extends the RPC request schema/client to accept and forward defender_config (including block_high_risk and tier classification toggles).
• Updates StackOneToolSet to resolve/validate defender at construction time and include it in dry-run + live RPC calls, with added tests and mock support.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/types.ts	Adds DefenderConfig type and DEFAULT_DEFENDER_CONFIG constant.
src/toolsets.ts	Adds defender to toolset config, resolves config in constructor, forwards defender_config in RPC execution.
src/toolsets.test.ts	Adds coverage for constructor storage and RPC/dryRun payload behaviors across defender modes.
src/schema.ts	Extends rpcActionRequestSchema to validate optional defender_config payload.
src/rpc-client.ts	Forwards defender_config into the outgoing RPC request body.
src/rpc-client.test.ts	Adds tests ensuring defender_config is forwarded/omitted as expected.
src/index.ts	Exports DEFAULT_DEFENDER_CONFIG and DefenderConfig from the public entrypoint.
mocks/handlers.stackone-rpc.ts	Updates MSW handler to accept/echo defender_config for test assertions.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cubic-dev-ai]

0 issues found across 2 files (changes from recent commits).

_{Requires human review: This PR introduces new business logic for security configuration and modifies the RPC request schema, which is a core system change requiring human review.}

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

_{Requires human review: This change introduces security-related configuration (prompt injection detection) and modifies RPC request schemas, which requires human oversight for architectural alignment.}

[cubic-dev-ai]

You're iterating quickly on this pull request. To help protect your rate limits, cubic has paused automatic reviews on new pushes for now—when you're ready for another review, comment @cubic-dev-ai review.

[glebedel]

Have we benchmarked performance impact here?
Can defender via our AI sdk be applied to non-stackone tools (i'd assume not).

If not, is the main value prop here to be able to have more granular control of when/for whom defender will be applied vs what we allow via project settings?

[glebedel]

This whole logic seems bloated, hard to read/parse. Did a good model spit that out as is? I'd have expected a leading model to create something simpler/cleaner by using default function parameters, using typeguards and maybe optional chaining?

[hiskudin]

Will look this over!

[hiskudin]

Reviewed here: bdfb570

[hiskudin]

I'll have to benchmark performance with and without defender.
Defender isn't really accessible within the AI SDK, it's configured on our backend, and yes, it'll give us more granular control programmatically, which was what I was aiming for in this PR. We can either explicitly define our defender settings OR state that we want to use project-level settings.

[shashi-stackone]

I think, since we discussed this last time on Slack somethng has been changed in terms of the requirements that I am missing here .. So my points might be came up due to lack of awareness on whats agreed .. However here my understanding

• ON by default contradicts my "opt-in, not by default" rule but I might be missing something
• useProjectSettings: true exists to honor the dashboard, but the default
  behavior overrides the dashboard silently, making SDK strict when you defer, silent when you override

@hiskudin we will discuss this tomorrow

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

[shashi-stackone]

@hiskudin I tested this locally and worked well

Just wondering if we can add some details about how run example overriding the connector and tools TOOL_NAME=calendly_get_current_user TOOL_BODY_JSON='{}' pnpm run:example examples/defender-config.ts

Otherwise PR looks good to me (LGTM)

[glebedel]

LGTM