sequentum-mcp 1.1.4 → 1.2.2

package/CHANGELOG.md

@@ -1,5 +1,104 @@
 # Changelog
 
+## [1.3.0] - TBD
+
+### Added
+
+- **ChatGPT Apps support:**
+  - CORS allowlist extended in `src/server/cors.ts` to permit `https://chatgpt.com`, `https://platform.openai.com`, and any subdomain depth under `chatgpt.com` (e.g. `connector.chatgpt.com`). `https://chat.openai.com` is intentionally omitted — OpenAI retired that origin in mid-2024 and redirects it to `chatgpt.com`; no live ChatGPT surface issues that Origin header. Same multi-level subdomain pattern and trust rationale as the Claude entries.
+  - `openWorldHint` added to all 13 write tools per the MCP spec. Tools that scrape arbitrary external websites on behalf of the caller (`start_agent`, `run_space_agents`, `start_agent_build`) are `true`. Tools that only mutate Sequentum's internal state (`stop_agent`, `kill_agent`, `delete_run`, `restore_agent_version`, schedule CRUD, `stop_agent_build`) are `false`. Required by OpenAI's ChatGPT App submission review.
+  - ChatGPT setup instructions added to `README.md` under "Set Up Your Client".
+- **Claude Connectors Directory support:**
+  - Origin-header allowlist (`src/server/cors.ts`) replaces the previous wildcard `Access-Control-Allow-Origin: *`. Permits Claude domains (`claude.ai`, `claude.com`, and all subdomain depths), Sequentum domains, and (when `DEBUG=1`) localhost / `127.0.0.1` / `[::1]`. Additional exact-match origins can be appended at startup via `ALLOWED_ORIGINS` (comma-separated; defaults are always preserved — see README). Requests from non-allowlisted browser origins to `/mcp` receive 403; requests without an `Origin` header (native MCP clients such as Cursor, Claude Desktop, Claude Code) pass through unaffected. `Vary: Origin` is set unconditionally so intermediate caches cannot conflate responses across origins.
+  - Privacy Policy section added to `README.md` with a plain-language data-handling summary and a link to `https://www.sequentum.com/privacy-policy`.
+- **Agent Builder tools** (3 new tools):
+  - `start_agent_build` — Start an AI-powered agent build session from a natural language prompt. The agent is saved to the workspace automatically once the AI creates it.
+  - `get_agent_build_status` — Poll the status of an agent build session. Stop polling on any terminal status: `completed`, `ready`, `error`, or `cancelled`. The session tears down automatically.
+  - `stop_agent_build` — Abort an in-progress build session early (optional). Has no effect once a terminal status is reached. Any agent already saved to the workspace persists.
+- **Agent Building prompts** (2 new prompts):
+  - `build-agent-from-prompt` — End-to-end workflow: resolve space, start session, poll until complete, fetch and show the resulting agent
+  - `inspect-agent-draft` — Check the status of an existing build session and show the resulting agent once available
+- **`validateString` extended** with `minLength`, `maxLength`, and `trim` options (via new `StringValidationOptions` interface). Fully backward-compatible — existing callers that pass a boolean are unaffected.
+- New types in `src/api/types.ts`: `AgentBuilderSessionStatus`, `ExternalStartAgentBuildRequest`, `ExternalStartAgentBuildResponse`, `ExternalSessionStatusResponse`
+- **User-controlled polling cadence for Agent Builder:**
+  - Added optional `pollingPreference` argument to both `build-agent-from-prompt` and `inspect-agent-draft` prompts. Accepts `"fast"` / `"normal"` / `"slow"` or any free-form instruction (e.g. `"poll every 5 seconds"`, `"be patient, this is a big site"`). When provided, the directive is templated into the prompt as a high-priority instruction the model honors when polling `get_agent_build_status`.
+  - Added a `POLLING CADENCE` paragraph to the `get_agent_build_status` tool description so user-expressed cadence preferences are also respected when the tool is invoked outside the prompts (e.g. via plain-chat usage). Default is a moderate cadence with backoff (~5s start, ~15–30s ceiling).
+- `title` annotation added to all 39 tools — human-readable label used by Anthropic's Connectors Directory and OpenAI's ChatGPT App submission.
+- `destructiveHint: false` explicitly set on `start_agent_build` and `stop_agent_build` (previously defaulted to `true` because `readOnlyHint: false` was set without `destructiveHint`).
+- **Sufficiency and prompt-handling policies.** New `src/server/policies.ts` is the single source of truth for two LLM-facing policy strings:
+  - `SUFFICIENCY_POLICY` is sent to every MCP client as the server `instructions` (on `initialize`). Directs the model to ask one consolidated clarifying question when a build/run request lacks an unambiguous URL, target data, or scope qualifier, and explicitly forbids silent extrapolation by analogy across sites or schemas.
+  - `PROMPT_HANDLING_POLICY` is appended to the `start_agent_build` tool description and inlined into the `build-agent-from-prompt` prompt template (rendered as a `**GUARDRAIL:**` preamble before the numbered steps). Directs the model to pass the user's wording through verbatim, allow only trivial normalizations (e.g. adding `https://`), and never invent fields, output formats, lazy-load instructions, pagination strategies, etc.
+  - Net behavior change: the model asks for missing details instead of silently expanding sparse user input into verbose `start_agent_build` prompts.
+
+### Documentation
+
+- `docs/tool-reference.md` — Updated count to 39 tools, new Agent Builder category in Quick Reference and full section
+- `docs/prompts-reference.md` — Updated count to 9 prompts, new Agent Building category in Quick Reference and full sections for both prompts
+- `docs/resources-reference.md` — Added cross-reference note explaining that saved agents become accessible via existing `sequentum://agents/{agentId}` resource
+
+### Security
+
+- Prompt arguments (`prompt`, `spaceName`, `sessionId`, `pollingPreference`) in `src/server/prompts.ts` are now sanitized before interpolation: newlines stripped, trimmed, and enforced per-argument length limits. Reduces prompt-injection surface via user-controlled strings.
+- `pollingPreference` de-elevated from an `IMPORTANT DIRECTIVE` banner to an advisory instruction, reducing its authority in the model's context.
+- `get_agent_build_status` handler now wraps raw backend `error` messages with a generic user-facing string (`"Build failed. Please review your prompt and try again."`). Raw error is still logged at `DEBUG=1` for operators. Prevents leakage of backend stack traces or internal endpoint paths to clients.
+- `sessionId` parameter validated with `maxLength: 256` at both agent-builder handler call sites.
+- `stop_agent_build` handler now returns structured JSON (`{ stopped: true, sessionId }`) instead of free-form English prose, consistent with all other tool handlers.
+- `redactDebugArgs` in `src/server/handlers.ts` extended to mask `prompt` and `comments` fields in addition to existing sensitive keys.
+- The new sufficiency and prompt-handling policies (see **Added**) reduce the surface for the model to silently extrapolate user requests across sites or schemas — defense in depth against accidental leakage of inferred-but-wrong details into a build.
+
+### Tests
+
+- Annotation regression tests strengthened in `src/server/handlers.test.ts`: every tool must have a non-empty `title` and `readOnlyHint` defined. Write-tool annotations are now validated against per-tool expectation tables — `openWorldHint` and `destructiveHint` must match an explicit expected value, not just be defined. Adding a new write tool without classifying both hints fails the build; changing an existing value without updating the table also fails.
+- Handler-dispatch tests added for the three agent-builder tools via `InMemoryTransport` + `Client`: `start_agent_build` rejects prompts below `minLength: 10`; `get_agent_build_status` sanitizes the `error` field; `stop_agent_build` returns the expected JSON shape.
+- CORS regression tests added in `src/server/cors.test.ts` covering exact-origin matches, claude/chatgpt subdomain depth (single and multi-level), `ALLOWED_ORIGINS` env-var append semantics, debug-mode localhost / IPv6 loopback, and adversarial rejections (e.g. `https://claude.ai.evil.com`, `https://notclaude.ai`, wrong scheme, uppercase).
+- Policy-wiring regression tests added in `src/server/handlers.test.ts`: `client.getInstructions()` equals `SUFFICIENCY_POLICY`; the `start_agent_build` tool description contains `PROMPT_HANDLING_POLICY`; the `build-agent-from-prompt` template embeds `PROMPT_HANDLING_POLICY`. Ensures the constants reach all three injection surfaces and prevents silent drift.
+
+---
+
+## [1.2.0] - 2026-03-12
+
+### Added
+
+- **MCP Prompts** (9 reusable workflow templates):
+  - `debug-agent` -- Diagnose why an agent is failing
+  - `agent-health-check` -- Comprehensive health overview for an agent
+  - `spending-report` -- Spending and credits report
+  - `cost-analysis` -- Analyze costs across agents
+  - `run-and-monitor` -- Start an agent and monitor until completion
+  - `space-overview` -- Overview of all agents in a space
+  - `daily-operations-report` -- Daily operations report across all agents
+  - `schedule-agent` -- Walk through creating or reviewing schedules
+  - `compare-runs` -- Compare last successful vs failed run
+- **MCP Resources** (18 read-only, URI-addressable data endpoints):
+  - 7 static resources: agent list, spaces, credits balance, monthly spending, agent costs, recent runs summary, upcoming schedules
+  - 11 resource templates: agent detail, agent versions, agent schedules, agent cost breakdown, agent runs, run status, run files, run diagnostics, latest failure, space detail, space agents
+- **Schedule Management** tools:
+  - `get_agent_schedule` -- Get details of a specific schedule
+  - `update_agent_schedule` -- Update an existing schedule's timing, parameters, or settings
+  - `enable_agent_schedule` -- Enable a previously disabled schedule
+  - `disable_agent_schedule` -- Disable a schedule without deleting it
+- New `src/server/handlers.test.ts` with handler unit tests
+- Expanded test coverage for API client and index module
+- Documentation: `docs/prompts-reference.md` and `docs/resources-reference.md`
+
+### Changed
+
+- **Major architecture refactoring**: Split monolithic `src/index.ts` (~2000 lines) into a modular structure:
+  - `src/server/tools.ts` -- Tool definitions and schemas
+  - `src/server/handlers.ts` -- MCP server factory and tool handler dispatch
+  - `src/server/http-server.ts` -- HTTP/Streamable transport, session management, OAuth discovery
+  - `src/server/prompts.ts` -- Prompt definitions and message builders
+  - `src/server/resources.ts` -- Resource and resource template definitions with URI dispatcher
+  - `src/api/api-client.ts` -- API client (moved from `src/`)
+  - `src/api/types.ts` -- TypeScript interfaces and enums (moved from `src/`)
+  - `src/utils/validation.ts` -- Input validation helpers (moved from `src/`)
+  - `src/utils/oauth-metadata.ts` -- OAuth metadata builder (moved from `src/`)
+- Extracted shared validation logic into `src/utils/validation.ts` to eliminate duplicate code
+- Added URI validation for resource endpoints
+- Improved atomic session control in HTTP server
+- Updated `docs/tool-reference.md` with the 4 new schedule tools (36 total)
+- Updated `README.md` with prompts, resources sections and references to new documentation
+
 ## [1.1.4] - 2026-03-04
 
 ### Added
@@ -92,6 +191,7 @@
 
 ---
 
+[1.2.0]: https://github.com/Sequentum/sequentum-mcp/compare/v1.1.4...v1.2.0
 [1.1.4]: https://github.com/Sequentum/sequentum-mcp/compare/v1.1.3...v1.1.4
 [1.1.3]: https://github.com/Sequentum/sequentum-mcp/compare/v1.0.2...v1.1.3
 [1.0.2]: https://github.com/Sequentum/sequentum-mcp/compare/v1.0.1...v1.0.2

package/README.md

@@ -5,7 +5,7 @@
 
 The [Sequentum MCP Server](https://mcp.sequentum.com) connects your AI coding assistant to Sequentum using the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction), giving your AI tools direct access to web scraping agents, run management, scheduling, analytics, and more. Sequentum hosts and manages a remote MCP server with OAuth authentication, so there's nothing to install.
 
-## [Tool Reference](./docs/tool-reference.md) | [Troubleshooting](./docs/troubleshooting.md) | [Changelog](./CHANGELOG.md)
+## [Tool Reference](./docs/tool-reference.md) | [Prompts Reference](./docs/prompts-reference.md) | [Resources Reference](./docs/resources-reference.md) | [Troubleshooting](./docs/troubleshooting.md) | [Changelog](./CHANGELOG.md)
 
 ## Key Features
 
@@ -85,6 +85,17 @@ Then, each team member connects individually:
 
 Once configured, enable the Sequentum connector in individual conversations via the **"+"** button on the lower left of the chat interface, then select **"Connectors"**.
 
+### ChatGPT
+
+> **Note:** While the Sequentum app is pending directory approval, you can connect via Developer Mode. Apps & Connectors → Developer Mode is currently available on **Plus, Pro, Business, Enterprise, and Education** plans (Education is web-only). On Business / Enterprise / Education accounts, only **workspace owners and admins** can access Advanced settings — regular members will not see the option. See [OpenAI's Developer Mode documentation](https://platform.openai.com/docs/developer-mode) for current eligibility.
+
+1. In ChatGPT, go to **Settings** > **Apps & Connectors** > **Advanced settings** and enable **Developer mode**.
+2. Navigate to **Settings** > **Apps & Connectors** and click **Create app** (it appears once Developer mode is enabled).
+3. Enter the connector name `Sequentum` and URL: `https://mcp.sequentum.com/mcp`
+4. Click **Create**. You'll be prompted to sign in with your Sequentum account via OAuth.
+
+Once connected, enable Sequentum in a conversation via the **+** button near the message composer, then select your connector from the list.
+
 ### Claude Code
 
 Run the following command in your terminal:
@@ -202,7 +213,7 @@ How much did I spend on server time vs exports last week?
 
 ## Available Tools
 
-The Sequentum MCP Server provides tools across 8 categories for interacting with the Sequentum platform. See the [Tool Reference](./docs/tool-reference.md) for detailed documentation.
+The Sequentum MCP Server provides 39 tools across 9 categories for interacting with the Sequentum platform. See the [Tool Reference](./docs/tool-reference.md) for detailed documentation.
 
 <!-- BEGIN AUTO GENERATED TOOLS -->
 
@@ -223,9 +234,13 @@ The Sequentum MCP Server provides tools across 8 categories for interacting with
 - **Version Management** (2 tools)
   - [`get_agent_versions`](docs/tool-reference.md#get_agent_versions)
   - [`restore_agent_version`](docs/tool-reference.md#restore_agent_version)
-- **Schedule Management** (4 tools)
+- **Schedule Management** (8 tools)
   - [`list_agent_schedules`](docs/tool-reference.md#list_agent_schedules)
+  - [`get_agent_schedule`](docs/tool-reference.md#get_agent_schedule)
   - [`create_agent_schedule`](docs/tool-reference.md#create_agent_schedule)
+  - [`update_agent_schedule`](docs/tool-reference.md#update_agent_schedule)
+  - [`enable_agent_schedule`](docs/tool-reference.md#enable_agent_schedule)
+  - [`disable_agent_schedule`](docs/tool-reference.md#disable_agent_schedule)
   - [`delete_agent_schedule`](docs/tool-reference.md#delete_agent_schedule)
   - [`get_scheduled_runs`](docs/tool-reference.md#get_scheduled_runs)
 - **Billing & Credits** (6 tools)
@@ -246,9 +261,67 @@ The Sequentum MCP Server provides tools across 8 categories for interacting with
   - [`get_records_summary`](docs/tool-reference.md#get_records_summary)
   - [`get_run_diagnostics`](docs/tool-reference.md#get_run_diagnostics)
   - [`get_latest_failure`](docs/tool-reference.md#get_latest_failure)
+- **Agent Builder** (3 tools)
+  - [`start_agent_build`](docs/tool-reference.md#start_agent_build)
+  - [`get_agent_build_status`](docs/tool-reference.md#get_agent_build_status)
+  - [`stop_agent_build`](docs/tool-reference.md#stop_agent_build)
 
 <!-- END AUTO GENERATED TOOLS -->
 
+## Available Prompts
+
+The server includes 9 reusable prompt templates that guide the AI through common multi-step workflows. See the [Prompts Reference](./docs/prompts-reference.md) for detailed documentation.
+
+<!-- BEGIN AUTO GENERATED PROMPTS -->
+
+- **Debugging & Diagnostics**
+  - [`debug-agent`](docs/prompts-reference.md#debug-agent) -- Diagnose why an agent is failing
+  - [`compare-runs`](docs/prompts-reference.md#compare-runs) -- Compare last successful vs failed run
+- **Health & Monitoring**
+  - [`agent-health-check`](docs/prompts-reference.md#agent-health-check) -- Comprehensive health overview for an agent
+  - [`daily-operations-report`](docs/prompts-reference.md#daily-operations-report) -- Daily ops report across all agents
+  - [`space-overview`](docs/prompts-reference.md#space-overview) -- Overview of all agents in a space
+- **Execution**
+  - [`run-and-monitor`](docs/prompts-reference.md#run-and-monitor) -- Start an agent and monitor until completion
+  - [`schedule-agent`](docs/prompts-reference.md#schedule-agent) -- Walk through creating a schedule
+- **Billing & Costs**
+  - [`spending-report`](docs/prompts-reference.md#spending-report) -- Spending and credits report
+  - [`cost-analysis`](docs/prompts-reference.md#cost-analysis) -- Analyze costs across agents
+- **Agent Building**
+  - [`build-agent-from-prompt`](docs/prompts-reference.md#build-agent-from-prompt) -- Build a new agent from a natural language description
+  - [`inspect-agent-draft`](docs/prompts-reference.md#inspect-agent-draft) -- Inspect a build session and decide whether to save or discard
+
+<!-- END AUTO GENERATED PROMPTS -->
+
+## Available Resources
+
+The server exposes 18 read-only resources (7 static + 11 templates) that AI clients can browse and pull into context. See the [Resources Reference](./docs/resources-reference.md) for detailed documentation.
+
+<!-- BEGIN AUTO GENERATED RESOURCES -->
+
+- **Static Resources** (7)
+  - [`sequentum://agents`](docs/resources-reference.md#agent-list) -- First page of all agents
+  - [`sequentum://spaces`](docs/resources-reference.md#spaces) -- All accessible spaces
+  - [`sequentum://billing/balance`](docs/resources-reference.md#credits-balance) -- Current credits balance
+  - [`sequentum://billing/spending`](docs/resources-reference.md#monthly-spending) -- Monthly spending summary
+  - [`sequentum://billing/agents-usage`](docs/resources-reference.md#agent-costs-current-month) -- Top agents by cost
+  - [`sequentum://analytics/runs`](docs/resources-reference.md#recent-runs-summary) -- Runs in the last 24 hours
+  - [`sequentum://analytics/upcoming-schedules`](docs/resources-reference.md#upcoming-schedules) -- Scheduled runs for next 7 days
+- **Resource Templates** (11)
+  - [`sequentum://agents/{agentId}`](docs/resources-reference.md#agent-detail) -- Agent detail with configuration
+  - [`sequentum://agents/{agentId}/versions`](docs/resources-reference.md#agent-versions) -- Agent version history
+  - [`sequentum://agents/{agentId}/schedules`](docs/resources-reference.md#agent-schedules) -- Agent scheduled tasks
+  - [`sequentum://agents/{agentId}/cost-breakdown`](docs/resources-reference.md#agent-cost-breakdown) -- Agent cost by usage type
+  - [`sequentum://agents/{agentId}/runs`](docs/resources-reference.md#agent-runs) -- Agent run history
+  - [`sequentum://agents/{agentId}/runs/{runId}`](docs/resources-reference.md#run-status) -- Specific run status
+  - [`sequentum://agents/{agentId}/runs/{runId}/files`](docs/resources-reference.md#run-files) -- Run output files
+  - [`sequentum://agents/{agentId}/runs/{runId}/diagnostics`](docs/resources-reference.md#run-diagnostics) -- Run error diagnostics
+  - [`sequentum://agents/{agentId}/latest-failure`](docs/resources-reference.md#latest-failure) -- Most recent failure diagnostics
+  - [`sequentum://spaces/{spaceId}`](docs/resources-reference.md#space-detail) -- Space details
+  - [`sequentum://spaces/{spaceId}/agents`](docs/resources-reference.md#space-agents) -- Agents in a space
+
+<!-- END AUTO GENERATED RESOURCES -->
+
 ## Troubleshooting
 
 | Error | Solution |
@@ -262,6 +335,34 @@ The Sequentum MCP Server provides tools across 8 categories for interacting with
 
 For more troubleshooting help, see the [Troubleshooting Guide](./docs/troubleshooting.md).
 
+## CORS Origin Allowlist
+
+When the MCP server is accessed from a browser (e.g. the Claude web app or the ChatGPT connector), it checks the `Origin` header against an allowlist.  By default the following origins are permitted:
+
+- `https://claude.ai`, `https://claude.com`, and all subdomains (e.g. `team.claude.ai`)
+- `https://chatgpt.com`, `https://platform.openai.com`, and all subdomains under `chatgpt.com` (e.g. `connector.chatgpt.com`)
+- `https://dashboard.sequentum.com`
+- `https://mcp.sequentum.com`
+- `http://localhost:<port>`, `http://127.0.0.1:<port>`, and `http://[::1]:<port>` when `DEBUG=1`
+
+To add your own origins (e.g. an internal dashboard), set the `ALLOWED_ORIGINS` environment variable to a comma-separated list of exact origins:
+
+```
+ALLOWED_ORIGINS="https://my-dashboard.example.com,https://other.example.com"
+```
+
+These origins are **appended** to the defaults — Claude, ChatGPT, and Sequentum access is preserved.  Wildcards and regular expressions are not supported via the env var; if you need a subdomain wildcard, add a `RegExp` entry directly in `src/server/cors.ts`.
+
+> **Note:** `Origin` matching is case-sensitive and does not include a path or query string.  Native MCP clients (Cursor, Claude Desktop, Claude Code) send no `Origin` header and are not affected by this allowlist.
+
+## Privacy Policy
+
+The Sequentum MCP Server accesses your Sequentum account data — including agent metadata, run history, scheduled tasks, billing information, and output files — solely to fulfill the requests you make through your AI assistant. By default, the MCP server acts as an authenticated proxy between your MCP client and the Sequentum API: request data is forwarded to the API and responses are returned to your client without being persisted or shared with third parties.
+
+Operators may enable verbose request logging via the `DEBUG=1` environment variable for troubleshooting. In that mode the server redacts `Authorization`, `Cookie`, and `x-api-key` headers, but writes request bodies (which may include tool arguments) to stderr. The hosted server at `mcp.sequentum.com` does not run with `DEBUG=1`.
+
+For the full Sequentum privacy policy, see [https://www.sequentum.com/privacy-policy](https://www.sequentum.com/privacy-policy).
+
 ## Links
 
 - [Sequentum MCP Server](https://mcp.sequentum.com)

package/dist/{api-client.d.ts → api/api-client.d.ts}

@@ -2,19 +2,23 @@
  * Sequentum API Client
  * Handles all HTTP communication with the Sequentum Control Center API
  */
-import { AgentApiModel, AgentRunApiModel, AgentRunFileApiModel, AgentVersionModel, StartAgentRequest, AgentScheduleApiModel, CreateScheduleRequest, UpcomingScheduleApiModel, CreditsBalanceApiModel, SpendingSummaryApiModel, CreditHistoryApiModel, AgentsUsageApiResponse, AgentCostBreakdownApiModel, AgentRunsApiResponse, SpaceApiModel, SpaceAgentApiModel, RunSpaceAgentsResultApiModel, RunsSummaryApiModel, RecordsSummaryApiModel, RunDiagnosticsApiModel, ListAgentsRequest, PaginatedAgentsResponse, RunRemoveMethod } from "./types.js";
+import { AgentApiModel, AgentRunApiModel, AgentRunFileApiModel, AgentVersionModel, StartAgentRequest, AgentScheduleApiModel, CreateScheduleRequest, UpdateScheduleRequest, UpcomingScheduleApiModel, CreditsBalanceApiModel, SpendingSummaryApiModel, CreditHistoryApiModel, AgentsUsageApiResponse, AgentCostBreakdownApiModel, AgentRunsApiResponse, SpaceApiModel, SpaceAgentApiModel, RunSpaceAgentsResultApiModel, RunsSummaryApiModel, RecordsSummaryApiModel, RunDiagnosticsApiModel, ListAgentsRequest, PaginatedAgentsResponse, RunRemoveMethod, ExternalStartAgentBuildRequest, ExternalStartAgentBuildResponse, ExternalSessionStatusResponse } from "./types.js";
 export declare class SequentumApiClient {
     private baseUrl;
     private apiKey;
     private accessToken;
     private requestTimeoutMs;
+    private maxRetries;
+    private baseDelayMs;
+    private maxDelayMs;
     /**
      * Create a new Sequentum API client
      * @param baseUrl - The base URL of the Sequentum API (e.g., https://dashboard.sequentum.com)
      * @param apiKey - The API key (sk-...) for authentication (optional if using OAuth2)
      * @param requestTimeoutMs - Request timeout in milliseconds (default: 30000)
+     * @param maxRetries - Maximum number of retries for transient failures (default: 3)
      */
-    constructor(baseUrl: string, apiKey?: string | null, requestTimeoutMs?: number);
+    constructor(baseUrl: string, apiKey?: string | null, requestTimeoutMs?: number, maxRetries?: number);
     /**
      * Set the OAuth2 access token for Bearer authentication
      * @param token - The access token
@@ -29,11 +33,60 @@ export declare class SequentumApiClient {
      */
     private getAuthorizationHeader;
     /**
-     * Make an authenticated request to the API
+     * Parse an error response body from the Sequentum API.
+     *
+     * The API returns errors in two formats:
+     *   - BadRequestError / InternalServerError: { statusCode, statusDescription, message, severity }
+     *   - ProblemDetails (RFC 7807):             { type, title, status, detail, instance }
+     *
+     * This method tries both formats and returns a human-readable message.
+     */
+    private parseErrorBody;
+    /**
+     * Parse the Retry-After header value into seconds.
+     * Supports both delta-seconds (e.g. "120") and HTTP-date formats.
+     * @returns seconds to wait, or null if header is missing/unparseable
+     */
+    private parseRetryAfter;
+    /**
+     * Build a typed error from an HTTP error response.
+     * Reads the response body, parses it as JSON (handling both API error formats),
+     * and returns the appropriate error class.
+     */
+    private buildErrorFromResponse;
+    /**
+     * Calculate delay for exponential backoff with jitter.
+     * @param attempt - 0-based attempt number
+     * @param retryAfterSeconds - Optional Retry-After hint from the server
+     */
+    private getRetryDelay;
+    /**
+     * Sleep for the given number of milliseconds.
+     */
+    private sleep;
+    /**
+     * Core HTTP method used by both request<T>() and requestVoid().
+     * Handles authentication, timeout, error parsing, and automatic retry
+     * for transient failures (429, 502, 503, 504).
+     *
+     * @param endpoint - API path (e.g. "/api/v1/agent/all")
+     * @param options - fetch() options (method, body, etc.)
+     * @returns The raw Response object on success
+     * @throws ApiRequestError (or subclass) on HTTP errors after retries are exhausted
+     * @throws AuthenticationError if no credentials are configured
+     * @throws Error on timeout or network failure
+     */
+    private fetchWithRetry;
+    /**
+     * Make an authenticated request to the API and parse the JSON response.
+     * Includes automatic retry for transient failures (429, 502, 503, 504) on
+     * idempotent methods.
      */
     private request;
     /**
-     * Make an authenticated request that doesn't expect a response body
+     * Make an authenticated request that doesn't expect a response body.
+     * Includes automatic retry for transient failures (429, 502, 503, 504) on
+     * idempotent methods.
      */
     private requestVoid;
     /**
@@ -140,6 +193,33 @@ export declare class SequentumApiClient {
      * @param scheduleId - The ID of the schedule to delete
      */
     deleteAgentSchedule(agentId: number, scheduleId: number): Promise<void>;
+    /**
+     * Get a specific schedule by ID
+     * @param agentId - The ID of the agent
+     * @param scheduleId - The ID of the schedule
+     * @returns The schedule details
+     */
+    getAgentSchedule(agentId: number, scheduleId: number): Promise<AgentScheduleApiModel>;
+    /**
+     * Update an existing schedule
+     * @param agentId - The ID of the agent
+     * @param scheduleId - The ID of the schedule to update
+     * @param request - The updated schedule configuration
+     * @returns The updated schedule
+     */
+    updateAgentSchedule(agentId: number, scheduleId: number, request: UpdateScheduleRequest): Promise<AgentScheduleApiModel>;
+    /**
+     * Enable a schedule so it runs according to its configuration
+     * @param agentId - The ID of the agent
+     * @param scheduleId - The ID of the schedule to enable
+     */
+    enableAgentSchedule(agentId: number, scheduleId: number): Promise<void>;
+    /**
+     * Disable a schedule so it will not run until re-enabled
+     * @param agentId - The ID of the agent
+     * @param scheduleId - The ID of the schedule to disable
+     */
+    disableAgentSchedule(agentId: number, scheduleId: number): Promise<void>;
     /**
      * Get upcoming scheduled runs
      * @param startDate - Optional start date (ISO format)
@@ -246,5 +326,27 @@ export declare class SequentumApiClient {
      * @param agentId - The ID of the agent
      */
     getLatestFailure(agentId: number): Promise<RunDiagnosticsApiModel>;
+    /**
+     * Start a new agent building session.
+     * Returns immediately with a sessionId — building runs asynchronously.
+     * Poll getAgentBuildStatus until status reaches a terminal value: "completed", "ready", "error", or "cancelled".
+     * @param request - The prompt and optional spaceId
+     */
+    startAgentBuild(request: ExternalStartAgentBuildRequest): Promise<ExternalStartAgentBuildResponse>;
+    /**
+     * Get the current status of an agent building session.
+     * Lightweight polling endpoint — call this until status reaches a terminal value: "completed", "ready", "error", or "cancelled".
+     * @param sessionId - The session ID returned from startAgentBuild
+     */
+    getAgentBuildStatus(sessionId: string): Promise<ExternalSessionStatusResponse>;
+    /**
+     * Abort an in-progress agent building session early.
+     * Has no effect once the session has already reached a terminal status.
+     * The agent draft (if already created) persists in the workspace — use
+     * the standard agents API to delete it if unwanted.
+     * Returns 204 No Content on success.
+     * @param sessionId - The session ID
+     */
+    stopAgentBuild(sessionId: string): Promise<void>;
 }
 //# sourceMappingURL=api-client.d.ts.map

package/dist/api/api-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../../src/api/api-client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EAEjB,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,EACrB,wBAAwB,EACxB,sBAAsB,EACtB,uBAAuB,EACvB,qBAAqB,EACrB,sBAAsB,EACtB,0BAA0B,EAC1B,oBAAoB,EACpB,aAAa,EACb,kBAAkB,EAClB,4BAA4B,EAC5B,mBAAmB,EACnB,sBAAsB,EACtB,sBAAsB,EACtB,iBAAiB,EACjB,uBAAuB,EAIvB,eAAe,EACf,8BAA8B,EAC9B,+BAA+B,EAC/B,6BAA6B,EAC9B,MAAM,YAAY,CAAC;AAUpB,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,UAAU,CAAS;IAE3B;;;;;;OAMG;gBAED,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,MAAM,GAAG,IAAW,EAC5B,gBAAgB,GAAE,MAAc,EAChC,UAAU,GAAE,MAA4B;IAU1C;;;OAGG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAI1C;;OAEG;IACH,cAAc,IAAI,MAAM,GAAG,IAAI;IAI/B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAc9B;;;;;;;;OAQG;IACH,OAAO,CAAC,cAAc;IAmBtB;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAoBvB;;;;OAIG;YACW,sBAAsB;IAkCpC;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAWrB;;OAEG;IACH,OAAO,CAAC,KAAK;IAIb;;;;;;;;;;;OAWG;YACW,cAAc;IA+E5B;;;;OAIG;YACW,OAAO;IAmBrB;;;;OAIG;YACW,WAAW;IAYzB;;;;OAIG;IACG,YAAY,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,aAAa,EAAE,GAAG,uBAAuB,CAAC;IA8BnG;;;OAGG;IACG,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAIvD;;;;OAIG;IACG,YAAY,CAChB,KAAK,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,aAAa,EAAE,CAAC;IAc3B;;;;OAIG;IACG,YAAY,CAChB,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAO9B;;;;OAIG;IACG,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAM7E;;;;;OAKG;IACG,UAAU,CACd,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,gBAAgB,GAAG,MAAM,CAAC;IAsBrC;;;;OAIG;IACG,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM9D;;;;;;OAMG;IACG,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM9D;;;;;;;OAOG;IACG,SAAS,CACb,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,YAAY,CAAC,EAAE,eAAe,GAC7B,OAAO,CAAC,IAAI,CAAC;IAWhB;;;;OAIG;IACG,WAAW,CACf,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAMlC;;;;;OAKG;IACG,eAAe,CACnB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAUnC;;;OAGG;IACG,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAMrE;;;;;OAKG;IACG,mBAAmB,CACvB,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAchB;;;OAGG;IACG,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,EAAE,CAAC;IAM1E;;;;;OAKG;IACG,mBAAmB,CACvB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,qBAAqB,CAAC;IA6BjC;;;;OAIG;IACG,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO7E;;;;;OAKG;IACG,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAM3F;;;;;;OAMG;IACG,mBAAmB,CACvB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,qBAAqB,CAAC;IA8BjC;;;;OAIG;IACG,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO7E;;;;OAIG;IACG,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO9E;;;;OAIG;IACG,oBAAoB,CACxB,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,wBAAwB,EAAE,CAAC;IActC;;OAEG;IACG,iBAAiB,IAAI,OAAO,CAAC,sBAAsB,CAAC;IAI1D;;;;OAIG;IACG,kBAAkB,CACtB,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,uBAAuB,CAAC;IAUnC;;;;OAIG;IACG,gBAAgB,CACpB,SAAS,CAAC,EAAE,MAAM,EAClB,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,qBAAqB,CAAC;IAUjC;;;;;;;;;;OAUG;IACG,cAAc,CAClB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,EAClB,cAAc,CAAC,EAAE,MAAM,EACvB,UAAU,CAAC,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,sBAAsB,CAAC;IAkBlC;;;;;;;OAOG;IACG,qBAAqB,CACzB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,0BAA0B,CAAC;IAatC;;;;;;;;;;OAUG;IACG,gBAAgB,CACpB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,EAClB,cAAc,CAAC,EAAE,MAAM,EACvB,UAAU,CAAC,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,oBAAoB,CAAC;IAqBhC;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;IAI9C;;;OAGG;IACG,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAIvD;;;OAGG;IACG,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAMpE;;;OAGG;IACG,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAM7D;;;;OAIG;IACG,cAAc,CAClB,OAAO,EAAE,MAAM,EACf,eAAe,CAAC,EAAE,MAAM,GACvB,OAAO,CAAC,4BAA4B,CAAC;IAgBxC;;;;;;OAMG;IACG,cAAc,CAClB,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,EACf,cAAc,CAAC,EAAE,OAAO,GACvB,OAAO,CAAC,mBAAmB,CAAC;IAa/B;;;;;OAKG;IACG,iBAAiB,CACrB,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,sBAAsB,CAAC;IAWlC;;;;OAIG;IACG,iBAAiB,CACrB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,sBAAsB,CAAC;IAMlC;;;OAGG;IACG,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAUxE;;;;;OAKG;IACG,eAAe,CACnB,OAAO,EAAE,8BAA8B,GACtC,OAAO,CAAC,+BAA+B,CAAC;IAa3C;;;;OAIG;IACG,mBAAmB,CACvB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,6BAA6B,CAAC;IAMzC;;;;;;;OAOG;IACG,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAMvD"}