manus-api 0.0.0-stage → 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sukka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -0,0 +1,359 @@
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var rl = require('@henrygd/queue/rl');
+var extractErrorMessage = require('foxts/extract-error-message');
+var wait = require('foxts/wait');
+
+const AGENT_PROFILES = [
+    'lite',
+    'standard',
+    'max'
+];
+/** Thinking effort. Only applies to the `max` profile. */ const AGENT_EFFORTS = [
+    'medium',
+    'high',
+    'extra',
+    'ultra'
+];
+/**
+ * Build the `agent_profile` value that the Manus API accepts.
+ *
+ * @throws {TypeError} when `effort` is combined with a profile other than `max`.
+ */ function formatAgentProfile(profile, effort) {
+    if (profile !== 'max') {
+        if (effort != null) {
+            throw new TypeError(`effort "${effort}" only applies to the "max" profile, got "${profile}"`);
+        }
+        return profile;
+    }
+    return effort == null ? 'max' : `max-${effort}`;
+}
+/** `manus-1.6-`, `2.0-`, `1.6` ... the version segment is ignored by the API and carries no information. */ const LEGACY_VERSION_PREFIX = /^(?:manus-)?\d+(?:\.\d+)*-?/;
+/**
+ * Normalize the profile reported by the API, which uses the legacy versioned form (`manus-1.6`,
+ * `manus-1.6-lite`, `manus-1.6-max-high`; P0 T4, T5, T8). A bare version means `standard`.
+ * Returns `undefined` for values this version does not know.
+ */ function parseAgentProfile(value) {
+    if (value == null) return undefined;
+    const rest = value.replace(LEGACY_VERSION_PREFIX, '');
+    if (rest === '' || rest === 'standard') return {
+        agent_profile: 'standard'
+    };
+    if (rest === 'lite') return {
+        agent_profile: 'lite'
+    };
+    if (rest === 'max') return {
+        agent_profile: 'max'
+    };
+    if (rest.startsWith('max-')) {
+        const effort = rest.slice('max-'.length);
+        if (AGENT_EFFORTS.includes(effort)) {
+            return {
+                agent_profile: 'max',
+                effort: effort
+            };
+        }
+    }
+    return undefined;
+}
+
+const MANUS_API_BASE_URL = 'https://api.manus.ai';
+/** Error codes seen so far: `unauthenticated` (401), `permission_denied` (403), `not_found` (404), `rate_limited` (429). */ class ManusApiError extends Error {
+    constructor(message, options){
+        super(message, {
+            cause: options.cause
+        });
+        this.name = 'ManusApiError';
+        this.status = options.status;
+        this.code = options.code;
+        this.requestId = options.requestId;
+    }
+}
+/** One process keeps its polling under `ratePerMinute` requests across all tasks it tracks (design D11). */ function createPollQueue(ratePerMinute, concurrency = 8) {
+    return rl.newQueue(concurrency, ratePerMinute, 60000);
+}
+const MAX_RATE_LIMIT_RETRIES = 5;
+const MAX_BACKOFF_MS = 60000;
+const TRAILING_SLASHES = /\/+$/;
+function backoffMs(attempt, retryAfterHeader) {
+    const retryAfter = retryAfterHeader == null ? Number.NaN : Number(retryAfterHeader) * 1000;
+    if (Number.isFinite(retryAfter) && retryAfter > 0) {
+        return Math.min(retryAfter, MAX_BACKOFF_MS);
+    }
+    return Math.min(1000 * 2 ** (attempt - 1) + Math.random() * 1000, MAX_BACKOFF_MS);
+}
+function headerNumber(headers, name) {
+    const value = headers.get(name);
+    if (value == null) return undefined;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : undefined;
+}
+class ManusClient {
+    constructor(options){
+        this.options = options;
+        this.baseUrl = (options.baseUrl ?? MANUS_API_BASE_URL).replace(TRAILING_SLASHES, '');
+        this.fetch = options.fetch ?? globalThis.fetch;
+        this.timeoutMs = options.timeoutMs ?? 60000;
+        this.transferTimeoutMs = options.transferTimeoutMs ?? 600000;
+        this.sleep = options.sleep ?? wait.wait;
+    }
+    userMe() {
+        return this.get('/v2/user.me');
+    }
+    projectCreate(body) {
+        return this.post('/v2/project.create', body);
+    }
+    projectList() {
+        return this.get('/v2/project.list');
+    }
+    taskCreate(body) {
+        return this.post('/v2/task.create', body);
+    }
+    taskDetail(taskId) {
+        return this.get('/v2/task.detail', {
+            task_id: taskId
+        }, true);
+    }
+    taskList(params = {}) {
+        return this.get('/v2/task.list', params);
+    }
+    taskListMessages(params) {
+        return this.get('/v2/task.listMessages', params, true);
+    }
+    taskSendMessage(body) {
+        return this.post('/v2/task.sendMessage', body);
+    }
+    taskStop(taskId) {
+        return this.post('/v2/task.stop', {
+            task_id: taskId
+        });
+    }
+    taskConfirmAction(body) {
+        return this.post('/v2/task.confirmAction', body);
+    }
+    /** Repeated deletes and unknown IDs both answer 404 `not_found` (P0 section 12). */ taskDelete(taskId) {
+        return this.post('/v2/task.delete', {
+            task_id: taskId
+        });
+    }
+    fileUpload(filename) {
+        return this.post('/v2/file.upload', {
+            filename
+        });
+    }
+    fileDetail(fileId) {
+        return this.get('/v2/file.detail', {
+            file_id: fileId
+        });
+    }
+    artifactList(params = {}) {
+        return this.get('/v2/artifact.list', params);
+    }
+    connectorList() {
+        return this.get('/v2/connector.list');
+    }
+    skillList(projectId) {
+        return this.get('/v2/skill.list', {
+            project_id: projectId
+        });
+    }
+    /**
+   * PUT to the presigned `upload_url` of `file.upload`. The URL points at a storage host, so the
+   * request carries no API key and no content type (P0 T10: only the host is signed). A `Blob`
+   * from `fs.openAsBlob` streams from disk and sets the content length.
+   */ async uploadToUrl(uploadUrl, body) {
+        const res = await this.transfer(uploadUrl, {
+            method: 'PUT',
+            body
+        });
+        if (!res.ok) {
+            throw new ManusApiError(`Upload to the presigned URL failed with HTTP ${res.status}`, {
+                status: res.status,
+                code: `http_${res.status}`
+            });
+        }
+    }
+    /** GET a presigned artifact URL (signed for 48 hours), with no API key; the caller streams the body. */ async downloadFromUrl(url) {
+        const res = await this.transfer(url, {
+            method: 'GET'
+        });
+        if (!res.ok) {
+            await res.body?.cancel();
+            throw new ManusApiError(`Download failed with HTTP ${res.status}`, {
+                status: res.status,
+                code: `http_${res.status}`
+            });
+        }
+        return res;
+    }
+    async transfer(url, init) {
+        try {
+            return await this.fetch(url, {
+                ...init,
+                signal: AbortSignal.timeout(this.transferTimeoutMs)
+            });
+        } catch (error) {
+            throw new ManusApiError(extractErrorMessage.extractErrorMessage(error) ?? 'transfer failed', {
+                status: 0,
+                code: 'network',
+                cause: error
+            });
+        }
+    }
+    get(endpoint, query, poll = false) {
+        return this.request('GET', endpoint, {
+            query,
+            poll
+        });
+    }
+    post(endpoint, body) {
+        return this.request('POST', endpoint, {
+            body
+        });
+    }
+    async request(method, endpoint, init) {
+        const url = new URL(this.baseUrl + endpoint);
+        if (init.query) {
+            const entries = Object.entries(init.query);
+            for(let i = 0, len = entries.length; i < len; i++){
+                const [key, value] = entries[i];
+                if (value !== undefined) url.searchParams.set(key, String(value));
+            }
+        }
+        let retriedAuth = false;
+        let rateLimitRetries = 0;
+        for(;;){
+            // eslint-disable-next-line no-await-in-loop -- sequential retry loop
+            const apiKey = await this.options.getApiKey();
+            const headers = {
+                'x-manus-api-key': apiKey,
+                accept: 'application/json'
+            };
+            if (init.body !== undefined) headers['content-type'] = 'application/json';
+            const send = async ()=>{
+                const res = await this.fetch(url, {
+                    method,
+                    headers,
+                    body: init.body === undefined ? undefined : JSON.stringify(init.body),
+                    signal: AbortSignal.timeout(this.timeoutMs)
+                });
+                return {
+                    res,
+                    text: await res.text()
+                };
+            };
+            let res;
+            let text;
+            try {
+                // eslint-disable-next-line no-await-in-loop -- sequential retry loop
+                ({ res, text } = await (init.poll && this.options.pollQueue ? this.options.pollQueue.add(send) : send()));
+            } catch (error) {
+                throw new ManusApiError(extractErrorMessage.extractErrorMessage(error) ?? 'request failed', {
+                    status: 0,
+                    code: 'network',
+                    cause: error
+                });
+            }
+            this.lastRateLimit = {
+                limit: headerNumber(res.headers, 'x-ratelimit-limit'),
+                remaining: headerNumber(res.headers, 'x-ratelimit-remaining'),
+                reset: headerNumber(res.headers, 'x-ratelimit-reset')
+            };
+            let json;
+            try {
+                json = text ? JSON.parse(text) : undefined;
+            } catch  {
+                json = undefined;
+            }
+            if (json && res.ok && json.ok !== false) {
+                return json;
+            }
+            if (!retriedAuth && res.status === 401 && this.options.onUnauthorized) {
+                retriedAuth = true;
+                // eslint-disable-next-line no-await-in-loop -- sequential retry loop
+                await this.options.onUnauthorized();
+                continue;
+            }
+            if (rateLimitRetries < MAX_RATE_LIMIT_RETRIES && res.status === 429) {
+                rateLimitRetries++;
+                // eslint-disable-next-line no-await-in-loop -- sequential retry loop
+                await this.sleep(backoffMs(rateLimitRetries, res.headers.get('retry-after')));
+                continue;
+            }
+            throw new ManusApiError(json?.error?.message ?? `Manus API ${method} ${endpoint} failed with HTTP ${res.status}`, {
+                status: res.status,
+                code: json?.error?.code ?? (res.status === 429 ? 'rate_limited' : `http_${res.status}`),
+                requestId: json?.request_id
+            });
+        }
+    }
+}
+
+/** Event `timestamp` and plan `started_at` are Unix milliseconds, serialized as decimal strings. */ function toMillis(value) {
+    if (value == null) return undefined;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : undefined;
+}
+/** All helpers below expect `events` in ascending order (`task.listMessages` with `order=asc`). */ function lastEventOfType(events, type) {
+    for(let i = events.length - 1; i >= 0; i--){
+        if (events[i].type === type) return events[i];
+    }
+    return undefined;
+}
+/**
+ * The agent's final answer: the last `assistant_message` with `delivery_kind: "result"` (P0 F3).
+ * Falls back to the last assistant message when no event carries `delivery_kind`.
+ */ function finalAssistantMessage(events) {
+    let fallback;
+    for(let i = events.length - 1; i >= 0; i--){
+        const event = events[i];
+        if (event.type !== 'assistant_message') continue;
+        if (event.assistant_message.delivery_kind === 'result') return event;
+        fallback ??= event;
+    }
+    return fallback;
+}
+function outputAttachments(events) {
+    return finalAssistantMessage(events)?.assistant_message.attachments ?? [];
+}
+function structuredOutput(events) {
+    return lastEventOfType(events, 'structured_output_result')?.structured_output_result;
+}
+function latestAgentStatus(events) {
+    return lastEventOfType(events, 'status_update')?.status_update.agent_status;
+}
+/**
+ * `task.stop` leaves the task `stopped` plus a `user_stop` event (P0 T12). The stop is only
+ * current when no user message came after it: a follow-up turn starts the task again.
+ */ function wasStoppedByUser(events) {
+    for(let i = events.length - 1; i >= 0; i--){
+        const type = events[i].type;
+        if (type === 'user_stop') return true;
+        if (type === 'user_message') return false;
+    }
+    return false;
+}
+/**
+ * Details of a pending `waiting` state, from the most recent `status_update`. Not observed in P0
+ * (questions arrived as a normal final answer), kept for the documented confirmation flow.
+ */ function pendingWaiting(events) {
+    const status = lastEventOfType(events, 'status_update')?.status_update;
+    return status?.agent_status === 'waiting' ? status.status_detail ?? {} : undefined;
+}
+
+exports.AGENT_EFFORTS = AGENT_EFFORTS;
+exports.AGENT_PROFILES = AGENT_PROFILES;
+exports.MANUS_API_BASE_URL = MANUS_API_BASE_URL;
+exports.ManusApiError = ManusApiError;
+exports.ManusClient = ManusClient;
+exports.createPollQueue = createPollQueue;
+exports.finalAssistantMessage = finalAssistantMessage;
+exports.formatAgentProfile = formatAgentProfile;
+exports.lastEventOfType = lastEventOfType;
+exports.latestAgentStatus = latestAgentStatus;
+exports.outputAttachments = outputAttachments;
+exports.parseAgentProfile = parseAgentProfile;
+exports.pendingWaiting = pendingWaiting;
+exports.structuredOutput = structuredOutput;
+exports.toMillis = toMillis;
+exports.wasStoppedByUser = wasStoppedByUser;

package/dist/index.d.ts

@@ -0,0 +1,523 @@
+import { Queue } from '@henrygd/queue/rl';
+
+declare const AGENT_PROFILES: readonly ["lite", "standard", "max"];
+type AgentProfile = typeof AGENT_PROFILES[number];
+/** Thinking effort. Only applies to the `max` profile. */
+declare const AGENT_EFFORTS: readonly ["medium", "high", "extra", "ultra"];
+type AgentEffort = typeof AGENT_EFFORTS[number];
+/** The `agent_profile` value accepted by the Manus API, e.g. `standard` or `max-high`. */
+type AgentProfileValue = Exclude<AgentProfile, 'max'> | 'max' | `max-${AgentEffort}`;
+/**
+ * Build the `agent_profile` value that the Manus API accepts.
+ *
+ * @throws {TypeError} when `effort` is combined with a profile other than `max`.
+ */
+declare function formatAgentProfile(profile: AgentProfile, effort?: AgentEffort): AgentProfileValue;
+interface ParsedAgentProfile {
+    agent_profile: AgentProfile;
+    effort?: AgentEffort;
+}
+/**
+ * Normalize the profile reported by the API, which uses the legacy versioned form (`manus-1.6`,
+ * `manus-1.6-lite`, `manus-1.6-max-high`; P0 T4, T5, T8). A bare version means `standard`.
+ * Returns `undefined` for values this version does not know.
+ */
+declare function parseAgentProfile(value: string | null | undefined): ParsedAgentProfile | undefined;
+
+/**
+ * Manus API v2 request and response shapes.
+ *
+ * Sources: `openapi_v2.json` from the official `manus-api` skill, and the P0 smoke test. Where the
+ * two disagree (int64 fields are serialized as decimal strings on the wire), the observed shape wins.
+ */
+/** int64 serialized by protobuf JSON as a decimal string; older docs say integer. */
+type Int64String = string | number;
+interface ApiError {
+    code?: string;
+    message?: string;
+}
+interface ErrorResponse {
+    ok: false;
+    request_id?: string;
+    error?: ApiError;
+}
+type TaskStatus = 'running' | 'stopped' | 'waiting' | 'error';
+type ShareVisibility = 'private' | 'team' | 'public';
+type TaskType = 'standard' | 'project' | 'agent_subtask';
+interface Task {
+    id: string;
+    status: TaskStatus;
+    /** Unix seconds */
+    created_at?: Int64String;
+    /** Unix seconds */
+    updated_at?: Int64String;
+    task_type?: TaskType;
+    share_visibility?: ShareVisibility;
+    title?: string;
+    credit_usage?: number;
+    task_url?: string;
+    created_by_api_key?: {
+        id?: string;
+        name?: string;
+    } | null;
+    /** Legacy form, e.g. `manus-1.6-max-high`. Normalize with `parseAgentProfile`. */
+    agent_profile?: string;
+    /** Optional and independent of `status`. Absent means unknown, not `false`. */
+    has_running_background_jobs?: boolean;
+    is_archived?: boolean;
+}
+type ContentPart = {
+    type: 'text';
+    text: string;
+    visibility?: 'visible' | 'hidden';
+} | {
+    type: 'file';
+    file_id?: string;
+    file_url?: string;
+    file_data?: string;
+    filename?: string;
+    mime_type?: string;
+    visibility?: 'visible';
+} | {
+    type: 'voice';
+    file_id?: string;
+    file_url?: string;
+    file_data?: string;
+    filename?: string;
+    mime_type?: string;
+    visibility?: 'visible';
+};
+interface Message {
+    content: string | ContentPart[];
+    connectors?: string[];
+    enable_skills?: string[];
+    force_skills?: string[];
+    /** Bare 22-character task IDs, at most 20. */
+    task_references?: string[];
+}
+/** Not in the public docs (biz proto `CreateTaskRequest` field 11); verified in P0 T2 and T4. */
+type ExecutionEnvironment = {
+    kind: 'sandbox';
+} | {
+    kind: 'device';
+    device_id: string;
+    working_directory: string;
+};
+interface CreateTaskRequest {
+    message: Message;
+    project_id?: string;
+    locale?: string;
+    interactive_mode?: boolean;
+    hide_in_task_list?: boolean;
+    share_visibility?: ShareVisibility;
+    agent_profile?: string;
+    title?: string;
+    structured_output_schema?: Record<string, unknown>;
+    execution_environment?: ExecutionEnvironment;
+}
+interface CreateTaskResponse {
+    task_id: string;
+    task_title?: string;
+    task_url?: string;
+    share_url?: string;
+    share_visibility?: ShareVisibility;
+}
+interface TaskDetailResponse {
+    task: Task;
+}
+interface ListTasksParams {
+    limit?: number;
+    cursor?: string;
+    order?: 'asc' | 'desc';
+    scope?: 'all' | 'agent_subtask' | 'project' | 'standard';
+    agent_id?: string;
+    project_id?: string;
+    oauth_client_id?: string;
+    api_key_id?: string;
+}
+interface ListTasksResponse {
+    data: Task[];
+    has_more?: boolean;
+    next_cursor?: string;
+}
+interface TaskAttachment {
+    type?: 'image' | 'file' | 'voice' | 'slides';
+    filename?: string;
+    url?: string;
+    /** Path inside the execution environment, e.g. `/home/ubuntu/report.md`. */
+    path?: string;
+    content_type?: string;
+    file_uid?: string;
+    version_uid?: string;
+}
+interface QuestionExpectation {
+    options?: string[];
+    selection_mode?: 'single' | 'multiple';
+    response_method?: 'send_message';
+}
+interface StatusDetail {
+    waiting_for_event_id?: string;
+    waiting_for_event_type?: string;
+    waiting_description?: string;
+    confirm_input_schema?: Record<string, unknown>;
+}
+interface PlanStep {
+    status?: 'todo' | 'doing' | 'done' | 'failed';
+    title?: string;
+    /** Unix milliseconds */
+    started_at?: Int64String | null;
+    /** Unix milliseconds */
+    end_at?: Int64String | null;
+}
+interface TaskEventBase {
+    id: string;
+    /** Unix milliseconds */
+    timestamp?: Int64String;
+}
+type TaskEvent = (TaskEventBase & {
+    type: 'user_message';
+    user_message: {
+        content?: string;
+        message_type?: 'text' | 'voice';
+        attachments?: TaskAttachment[];
+        hidden_content?: string[];
+    };
+}) | (TaskEventBase & {
+    type: 'assistant_message';
+    assistant_message: {
+        content?: string;
+        attachments?: TaskAttachment[];
+        question_expectation?: QuestionExpectation;
+        /** `opening`, `progress` or `result` (P0). */
+        delivery_kind?: string;
+    };
+}) | (TaskEventBase & {
+    type: 'error_message';
+    error_message: {
+        error_type?: string;
+        content?: string;
+    };
+}) | (TaskEventBase & {
+    type: 'status_update';
+    status_update: {
+        agent_status?: TaskStatus;
+        status_detail?: StatusDetail;
+        brief?: string;
+        description?: string;
+    };
+}) | (TaskEventBase & {
+    type: 'tool_used';
+    tool_used: {
+        tool?: string;
+        action_id?: string;
+        status?: 'success' | 'error' | 'rollback' | 'pending_confirmation';
+        brief?: string;
+        description?: string;
+        message?: {
+            action?: string;
+            param?: string;
+        };
+        params?: Record<string, unknown>;
+        result?: Record<string, unknown>;
+    };
+}) | (TaskEventBase & {
+    type: 'plan_update';
+    plan_update: {
+        steps?: PlanStep[];
+    };
+}) | (TaskEventBase & {
+    type: 'new_plan_step';
+    new_plan_step: {
+        step_id?: string;
+        title?: string;
+    };
+}) | (TaskEventBase & {
+    type: 'explanation';
+    explanation: {
+        content?: string;
+    };
+}) | (TaskEventBase & {
+    type: 'user_stop';
+}) | (TaskEventBase & {
+    type: 'structured_output_result';
+    structured_output_result: {
+        success?: boolean;
+        value?: Record<string, unknown>;
+        error?: string | null;
+    };
+});
+type TaskEventType = TaskEvent['type'];
+interface ListMessagesParams {
+    task_id: string;
+    limit?: number;
+    cursor?: string;
+    start_event_id?: string;
+    order?: 'asc' | 'desc';
+    /** `tool_used`, `plan_update`, `new_plan_step` and `explanation` are only returned when true. */
+    verbose?: boolean;
+    slides_format?: 'html' | 'pptx';
+}
+interface ListMessagesResponse {
+    task_id: string;
+    messages: TaskEvent[];
+    has_more?: boolean;
+    next_cursor?: string;
+}
+interface SendMessageRequest {
+    task_id: string;
+    message: Message;
+    /** Applies to this and later turns. Omit to keep the current profile. */
+    agent_profile?: string;
+    /** Armed for the next finish only; a new schema replaces the previous one. */
+    structured_output_schema?: Record<string, unknown>;
+    clear_connectors?: boolean;
+}
+interface SendMessageResponse {
+    task_id: string;
+}
+interface ConfirmActionRequest {
+    task_id: string;
+    /** `status_update.status_detail.waiting_for_event_id` */
+    event_id: string;
+    input?: Record<string, unknown>;
+}
+interface ConfirmActionResponse {
+    task_id: string;
+    /** `false` when the input was valid but the pending action did not consume it. */
+    confirmed?: boolean;
+}
+interface DeleteTaskResponse {
+    id: string;
+    deleted: boolean;
+}
+interface Project {
+    id: string;
+    name?: string;
+    /** Unix seconds. `project.create` returns the Go zero time `-62135596800` (server bug). */
+    created_at?: Int64String;
+    instruction?: string;
+}
+interface CreateProjectRequest {
+    name: string;
+    instruction?: string;
+}
+interface CreateProjectResponse {
+    project: Project;
+}
+interface ListProjectsResponse {
+    data: Project[];
+}
+interface UserMeResponse {
+    user_id: string;
+    message?: string;
+    /** Not documented, returned in P0 T1. */
+    name?: string;
+    email?: string;
+    avatar_url?: string;
+}
+type FileStatus = 'pending' | 'uploaded' | 'deleted' | 'error';
+interface FileRecord {
+    id: string;
+    filename?: string;
+    status?: FileStatus;
+    /** Unix seconds */
+    created_at?: Int64String;
+}
+interface FileDetail extends FileRecord {
+    bytes?: Int64String;
+    content_type?: string;
+    /** Unix seconds; files live 48 hours. */
+    expires_at?: Int64String;
+    error_message?: string | null;
+}
+interface UploadFileResponse {
+    file: FileRecord;
+    /** Presigned PUT URL, valid for 3 minutes. */
+    upload_url: string;
+    /** Unix seconds */
+    upload_expires_at?: Int64String;
+}
+interface FileDetailResponse {
+    file: FileDetail;
+    /** Presigned GET URL, valid for at most 3 minutes. Only while `file.status` is `uploaded`. */
+    download_url?: string;
+    download_expires_at?: Int64String;
+}
+type ArtifactType = 'website' | 'mobile_app' | 'game' | 'documents' | 'slides' | 'spreadsheets' | 'images' | 'videos' | 'audio' | 'others';
+interface ArtifactSource {
+    kind?: 'oauth_client' | 'api_key';
+    oauth_client_id?: string;
+    api_key_id?: string;
+    name?: string;
+}
+interface Artifact {
+    id: string;
+    task_id?: string;
+    task_title?: string;
+    filename?: string;
+    display_name?: string;
+    type?: ArtifactType;
+    file_type?: 'file' | 'image' | 'slide' | 'website' | 'webdev';
+    content_type?: string;
+    url?: string;
+    cover_image?: string;
+    favorite?: boolean;
+    /** Unix seconds */
+    updated_at?: Int64String;
+    platform_type?: number;
+    logo?: string;
+    resource_uri?: string;
+    source?: ArtifactSource;
+}
+interface ListArtifactsParams {
+    limit?: number;
+    cursor?: string;
+    name?: string;
+    type?: 'all' | ArtifactType;
+    favorite?: boolean;
+    oauth_client_id?: string;
+    api_key_id?: string;
+}
+interface ListArtifactsResponse {
+    data: Artifact[];
+    has_more?: boolean;
+    next_cursor?: string;
+}
+interface ConnectorInfo {
+    id: string;
+    name?: string;
+    type?: 'builtin' | 'byok' | 'mcp';
+    description?: string;
+    category?: string;
+}
+interface ListConnectorsResponse {
+    data: ConnectorInfo[];
+}
+interface Skill {
+    id: string;
+    name?: string;
+    description?: string;
+    owner_type?: 'personal' | 'official' | 'team' | 'project' | 'app';
+    creator_info?: {
+        user_id?: string;
+        name?: string;
+    };
+    created_at?: Int64String;
+    updated_at?: Int64String;
+}
+interface ListSkillsResponse {
+    data: Skill[];
+}
+/** Values of the `x-ratelimit-*` response headers. */
+interface RateLimitInfo {
+    limit?: number;
+    remaining?: number;
+    /** Seconds until the window resets. */
+    reset?: number;
+}
+
+declare const MANUS_API_BASE_URL = "https://api.manus.ai";
+interface ManusApiErrorOptions extends ErrorOptions {
+    /** HTTP status, or 0 for a network failure. */
+    status: number;
+    code: string;
+    requestId?: string;
+}
+/** Error codes seen so far: `unauthenticated` (401), `permission_denied` (403), `not_found` (404), `rate_limited` (429). */
+declare class ManusApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly requestId: string | undefined;
+    constructor(message: string, options: ManusApiErrorOptions);
+}
+type PollQueue = Pick<Queue, 'add'>;
+interface ManusClientOptions {
+    /** Called on every request; cache inside the provider. Never logged. */
+    getApiKey: () => string | Promise<string>;
+    /** Called once after a 401 before the single retry, so a rotated key can be re-read (design D15.1). */
+    onUnauthorized?: () => void | Promise<void>;
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+    /** Per API request. */
+    timeoutMs?: number;
+    /** Per presigned upload or download, which can carry a whole artifact. */
+    transferTimeoutMs?: number;
+    /** Shared budget for `task.detail` and `task.listMessages`; see `createPollQueue`. */
+    pollQueue?: PollQueue;
+    sleep?: (ms: number) => Promise<void>;
+}
+/** One process keeps its polling under `ratePerMinute` requests across all tasks it tracks (design D11). */
+declare function createPollQueue(ratePerMinute: number, concurrency?: number): Queue;
+declare class ManusClient {
+    private readonly options;
+    /** Values of the `x-ratelimit-*` headers from the most recent response. */
+    lastRateLimit: RateLimitInfo | undefined;
+    private readonly baseUrl;
+    private readonly fetch;
+    private readonly timeoutMs;
+    private readonly transferTimeoutMs;
+    private readonly sleep;
+    constructor(options: ManusClientOptions);
+    userMe(): Promise<UserMeResponse>;
+    projectCreate(body: CreateProjectRequest): Promise<CreateProjectResponse>;
+    projectList(): Promise<ListProjectsResponse>;
+    taskCreate(body: CreateTaskRequest): Promise<CreateTaskResponse>;
+    taskDetail(taskId: string): Promise<TaskDetailResponse>;
+    taskList(params?: ListTasksParams): Promise<ListTasksResponse>;
+    taskListMessages(params: ListMessagesParams): Promise<ListMessagesResponse>;
+    taskSendMessage(body: SendMessageRequest): Promise<SendMessageResponse>;
+    taskStop(taskId: string): Promise<Record<string, never>>;
+    taskConfirmAction(body: ConfirmActionRequest): Promise<ConfirmActionResponse>;
+    /** Repeated deletes and unknown IDs both answer 404 `not_found` (P0 section 12). */
+    taskDelete(taskId: string): Promise<DeleteTaskResponse>;
+    fileUpload(filename: string): Promise<UploadFileResponse>;
+    fileDetail(fileId: string): Promise<FileDetailResponse>;
+    artifactList(params?: ListArtifactsParams): Promise<ListArtifactsResponse>;
+    connectorList(): Promise<ListConnectorsResponse>;
+    skillList(projectId?: string): Promise<ListSkillsResponse>;
+    /**
+     * PUT to the presigned `upload_url` of `file.upload`. The URL points at a storage host, so the
+     * request carries no API key and no content type (P0 T10: only the host is signed). A `Blob`
+     * from `fs.openAsBlob` streams from disk and sets the content length.
+     */
+    uploadToUrl(uploadUrl: string, body: Blob): Promise<void>;
+    /** GET a presigned artifact URL (signed for 48 hours), with no API key; the caller streams the body. */
+    downloadFromUrl(url: string): Promise<Response>;
+    private transfer;
+    private get;
+    private post;
+    private request;
+}
+
+type EventOf<T extends TaskEventType> = Extract<TaskEvent, {
+    type: T;
+}>;
+/** Event `timestamp` and plan `started_at` are Unix milliseconds, serialized as decimal strings. */
+declare function toMillis(value: Int64String | null | undefined): number | undefined;
+/** All helpers below expect `events` in ascending order (`task.listMessages` with `order=asc`). */
+declare function lastEventOfType<T extends TaskEventType>(events: readonly TaskEvent[], type: T): EventOf<T> | undefined;
+/**
+ * The agent's final answer: the last `assistant_message` with `delivery_kind: "result"` (P0 F3).
+ * Falls back to the last assistant message when no event carries `delivery_kind`.
+ */
+declare function finalAssistantMessage(events: readonly TaskEvent[]): EventOf<'assistant_message'> | undefined;
+declare function outputAttachments(events: readonly TaskEvent[]): TaskAttachment[];
+declare function structuredOutput(events: readonly TaskEvent[]): {
+    success?: boolean;
+    value?: Record<string, unknown>;
+    error?: string | null;
+} | undefined;
+declare function latestAgentStatus(events: readonly TaskEvent[]): TaskStatus | undefined;
+/**
+ * `task.stop` leaves the task `stopped` plus a `user_stop` event (P0 T12). The stop is only
+ * current when no user message came after it: a follow-up turn starts the task again.
+ */
+declare function wasStoppedByUser(events: readonly TaskEvent[]): boolean;
+/**
+ * Details of a pending `waiting` state, from the most recent `status_update`. Not observed in P0
+ * (questions arrived as a normal final answer), kept for the documented confirmation flow.
+ */
+declare function pendingWaiting(events: readonly TaskEvent[]): StatusDetail | undefined;
+
+export { AGENT_EFFORTS, AGENT_PROFILES, MANUS_API_BASE_URL, ManusApiError, ManusClient, createPollQueue, finalAssistantMessage, formatAgentProfile, lastEventOfType, latestAgentStatus, outputAttachments, parseAgentProfile, pendingWaiting, structuredOutput, toMillis, wasStoppedByUser };
+export type { AgentEffort, AgentProfile, AgentProfileValue, ApiError, Artifact, ArtifactSource, ArtifactType, ConfirmActionRequest, ConfirmActionResponse, ConnectorInfo, ContentPart, CreateProjectRequest, CreateProjectResponse, CreateTaskRequest, CreateTaskResponse, DeleteTaskResponse, ErrorResponse, ExecutionEnvironment, FileDetail, FileDetailResponse, FileRecord, FileStatus, Int64String, ListArtifactsParams, ListArtifactsResponse, ListConnectorsResponse, ListMessagesParams, ListMessagesResponse, ListProjectsResponse, ListSkillsResponse, ListTasksParams, ListTasksResponse, ManusApiErrorOptions, ManusClientOptions, Message, ParsedAgentProfile, PlanStep, PollQueue, Project, QuestionExpectation, RateLimitInfo, SendMessageRequest, SendMessageResponse, ShareVisibility, Skill, StatusDetail, Task, TaskAttachment, TaskDetailResponse, TaskEvent, TaskEventType, TaskStatus, TaskType, UploadFileResponse, UserMeResponse };

package/dist/index.mjs

@@ -0,0 +1,342 @@
+import { newQueue } from '@henrygd/queue/rl';
+import { extractErrorMessage } from 'foxts/extract-error-message';
+import { wait } from 'foxts/wait';
+
+const AGENT_PROFILES = [
+    'lite',
+    'standard',
+    'max'
+];
+/** Thinking effort. Only applies to the `max` profile. */ const AGENT_EFFORTS = [
+    'medium',
+    'high',
+    'extra',
+    'ultra'
+];
+/**
+ * Build the `agent_profile` value that the Manus API accepts.
+ *
+ * @throws {TypeError} when `effort` is combined with a profile other than `max`.
+ */ function formatAgentProfile(profile, effort) {
+    if (profile !== 'max') {
+        if (effort != null) {
+            throw new TypeError(`effort "${effort}" only applies to the "max" profile, got "${profile}"`);
+        }
+        return profile;
+    }
+    return effort == null ? 'max' : `max-${effort}`;
+}
+/** `manus-1.6-`, `2.0-`, `1.6` ... the version segment is ignored by the API and carries no information. */ const LEGACY_VERSION_PREFIX = /^(?:manus-)?\d+(?:\.\d+)*-?/;
+/**
+ * Normalize the profile reported by the API, which uses the legacy versioned form (`manus-1.6`,
+ * `manus-1.6-lite`, `manus-1.6-max-high`; P0 T4, T5, T8). A bare version means `standard`.
+ * Returns `undefined` for values this version does not know.
+ */ function parseAgentProfile(value) {
+    if (value == null) return undefined;
+    const rest = value.replace(LEGACY_VERSION_PREFIX, '');
+    if (rest === '' || rest === 'standard') return {
+        agent_profile: 'standard'
+    };
+    if (rest === 'lite') return {
+        agent_profile: 'lite'
+    };
+    if (rest === 'max') return {
+        agent_profile: 'max'
+    };
+    if (rest.startsWith('max-')) {
+        const effort = rest.slice('max-'.length);
+        if (AGENT_EFFORTS.includes(effort)) {
+            return {
+                agent_profile: 'max',
+                effort: effort
+            };
+        }
+    }
+    return undefined;
+}
+
+const MANUS_API_BASE_URL = 'https://api.manus.ai';
+/** Error codes seen so far: `unauthenticated` (401), `permission_denied` (403), `not_found` (404), `rate_limited` (429). */ class ManusApiError extends Error {
+    constructor(message, options){
+        super(message, {
+            cause: options.cause
+        });
+        this.name = 'ManusApiError';
+        this.status = options.status;
+        this.code = options.code;
+        this.requestId = options.requestId;
+    }
+}
+/** One process keeps its polling under `ratePerMinute` requests across all tasks it tracks (design D11). */ function createPollQueue(ratePerMinute, concurrency = 8) {
+    return newQueue(concurrency, ratePerMinute, 60000);
+}
+const MAX_RATE_LIMIT_RETRIES = 5;
+const MAX_BACKOFF_MS = 60000;
+const TRAILING_SLASHES = /\/+$/;
+function backoffMs(attempt, retryAfterHeader) {
+    const retryAfter = retryAfterHeader == null ? Number.NaN : Number(retryAfterHeader) * 1000;
+    if (Number.isFinite(retryAfter) && retryAfter > 0) {
+        return Math.min(retryAfter, MAX_BACKOFF_MS);
+    }
+    return Math.min(1000 * 2 ** (attempt - 1) + Math.random() * 1000, MAX_BACKOFF_MS);
+}
+function headerNumber(headers, name) {
+    const value = headers.get(name);
+    if (value == null) return undefined;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : undefined;
+}
+class ManusClient {
+    constructor(options){
+        this.options = options;
+        this.baseUrl = (options.baseUrl ?? MANUS_API_BASE_URL).replace(TRAILING_SLASHES, '');
+        this.fetch = options.fetch ?? globalThis.fetch;
+        this.timeoutMs = options.timeoutMs ?? 60000;
+        this.transferTimeoutMs = options.transferTimeoutMs ?? 600000;
+        this.sleep = options.sleep ?? wait;
+    }
+    userMe() {
+        return this.get('/v2/user.me');
+    }
+    projectCreate(body) {
+        return this.post('/v2/project.create', body);
+    }
+    projectList() {
+        return this.get('/v2/project.list');
+    }
+    taskCreate(body) {
+        return this.post('/v2/task.create', body);
+    }
+    taskDetail(taskId) {
+        return this.get('/v2/task.detail', {
+            task_id: taskId
+        }, true);
+    }
+    taskList(params = {}) {
+        return this.get('/v2/task.list', params);
+    }
+    taskListMessages(params) {
+        return this.get('/v2/task.listMessages', params, true);
+    }
+    taskSendMessage(body) {
+        return this.post('/v2/task.sendMessage', body);
+    }
+    taskStop(taskId) {
+        return this.post('/v2/task.stop', {
+            task_id: taskId
+        });
+    }
+    taskConfirmAction(body) {
+        return this.post('/v2/task.confirmAction', body);
+    }
+    /** Repeated deletes and unknown IDs both answer 404 `not_found` (P0 section 12). */ taskDelete(taskId) {
+        return this.post('/v2/task.delete', {
+            task_id: taskId
+        });
+    }
+    fileUpload(filename) {
+        return this.post('/v2/file.upload', {
+            filename
+        });
+    }
+    fileDetail(fileId) {
+        return this.get('/v2/file.detail', {
+            file_id: fileId
+        });
+    }
+    artifactList(params = {}) {
+        return this.get('/v2/artifact.list', params);
+    }
+    connectorList() {
+        return this.get('/v2/connector.list');
+    }
+    skillList(projectId) {
+        return this.get('/v2/skill.list', {
+            project_id: projectId
+        });
+    }
+    /**
+   * PUT to the presigned `upload_url` of `file.upload`. The URL points at a storage host, so the
+   * request carries no API key and no content type (P0 T10: only the host is signed). A `Blob`
+   * from `fs.openAsBlob` streams from disk and sets the content length.
+   */ async uploadToUrl(uploadUrl, body) {
+        const res = await this.transfer(uploadUrl, {
+            method: 'PUT',
+            body
+        });
+        if (!res.ok) {
+            throw new ManusApiError(`Upload to the presigned URL failed with HTTP ${res.status}`, {
+                status: res.status,
+                code: `http_${res.status}`
+            });
+        }
+    }
+    /** GET a presigned artifact URL (signed for 48 hours), with no API key; the caller streams the body. */ async downloadFromUrl(url) {
+        const res = await this.transfer(url, {
+            method: 'GET'
+        });
+        if (!res.ok) {
+            await res.body?.cancel();
+            throw new ManusApiError(`Download failed with HTTP ${res.status}`, {
+                status: res.status,
+                code: `http_${res.status}`
+            });
+        }
+        return res;
+    }
+    async transfer(url, init) {
+        try {
+            return await this.fetch(url, {
+                ...init,
+                signal: AbortSignal.timeout(this.transferTimeoutMs)
+            });
+        } catch (error) {
+            throw new ManusApiError(extractErrorMessage(error) ?? 'transfer failed', {
+                status: 0,
+                code: 'network',
+                cause: error
+            });
+        }
+    }
+    get(endpoint, query, poll = false) {
+        return this.request('GET', endpoint, {
+            query,
+            poll
+        });
+    }
+    post(endpoint, body) {
+        return this.request('POST', endpoint, {
+            body
+        });
+    }
+    async request(method, endpoint, init) {
+        const url = new URL(this.baseUrl + endpoint);
+        if (init.query) {
+            const entries = Object.entries(init.query);
+            for(let i = 0, len = entries.length; i < len; i++){
+                const [key, value] = entries[i];
+                if (value !== undefined) url.searchParams.set(key, String(value));
+            }
+        }
+        let retriedAuth = false;
+        let rateLimitRetries = 0;
+        for(;;){
+            // eslint-disable-next-line no-await-in-loop -- sequential retry loop
+            const apiKey = await this.options.getApiKey();
+            const headers = {
+                'x-manus-api-key': apiKey,
+                accept: 'application/json'
+            };
+            if (init.body !== undefined) headers['content-type'] = 'application/json';
+            const send = async ()=>{
+                const res = await this.fetch(url, {
+                    method,
+                    headers,
+                    body: init.body === undefined ? undefined : JSON.stringify(init.body),
+                    signal: AbortSignal.timeout(this.timeoutMs)
+                });
+                return {
+                    res,
+                    text: await res.text()
+                };
+            };
+            let res;
+            let text;
+            try {
+                // eslint-disable-next-line no-await-in-loop -- sequential retry loop
+                ({ res, text } = await (init.poll && this.options.pollQueue ? this.options.pollQueue.add(send) : send()));
+            } catch (error) {
+                throw new ManusApiError(extractErrorMessage(error) ?? 'request failed', {
+                    status: 0,
+                    code: 'network',
+                    cause: error
+                });
+            }
+            this.lastRateLimit = {
+                limit: headerNumber(res.headers, 'x-ratelimit-limit'),
+                remaining: headerNumber(res.headers, 'x-ratelimit-remaining'),
+                reset: headerNumber(res.headers, 'x-ratelimit-reset')
+            };
+            let json;
+            try {
+                json = text ? JSON.parse(text) : undefined;
+            } catch  {
+                json = undefined;
+            }
+            if (json && res.ok && json.ok !== false) {
+                return json;
+            }
+            if (!retriedAuth && res.status === 401 && this.options.onUnauthorized) {
+                retriedAuth = true;
+                // eslint-disable-next-line no-await-in-loop -- sequential retry loop
+                await this.options.onUnauthorized();
+                continue;
+            }
+            if (rateLimitRetries < MAX_RATE_LIMIT_RETRIES && res.status === 429) {
+                rateLimitRetries++;
+                // eslint-disable-next-line no-await-in-loop -- sequential retry loop
+                await this.sleep(backoffMs(rateLimitRetries, res.headers.get('retry-after')));
+                continue;
+            }
+            throw new ManusApiError(json?.error?.message ?? `Manus API ${method} ${endpoint} failed with HTTP ${res.status}`, {
+                status: res.status,
+                code: json?.error?.code ?? (res.status === 429 ? 'rate_limited' : `http_${res.status}`),
+                requestId: json?.request_id
+            });
+        }
+    }
+}
+
+/** Event `timestamp` and plan `started_at` are Unix milliseconds, serialized as decimal strings. */ function toMillis(value) {
+    if (value == null) return undefined;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : undefined;
+}
+/** All helpers below expect `events` in ascending order (`task.listMessages` with `order=asc`). */ function lastEventOfType(events, type) {
+    for(let i = events.length - 1; i >= 0; i--){
+        if (events[i].type === type) return events[i];
+    }
+    return undefined;
+}
+/**
+ * The agent's final answer: the last `assistant_message` with `delivery_kind: "result"` (P0 F3).
+ * Falls back to the last assistant message when no event carries `delivery_kind`.
+ */ function finalAssistantMessage(events) {
+    let fallback;
+    for(let i = events.length - 1; i >= 0; i--){
+        const event = events[i];
+        if (event.type !== 'assistant_message') continue;
+        if (event.assistant_message.delivery_kind === 'result') return event;
+        fallback ??= event;
+    }
+    return fallback;
+}
+function outputAttachments(events) {
+    return finalAssistantMessage(events)?.assistant_message.attachments ?? [];
+}
+function structuredOutput(events) {
+    return lastEventOfType(events, 'structured_output_result')?.structured_output_result;
+}
+function latestAgentStatus(events) {
+    return lastEventOfType(events, 'status_update')?.status_update.agent_status;
+}
+/**
+ * `task.stop` leaves the task `stopped` plus a `user_stop` event (P0 T12). The stop is only
+ * current when no user message came after it: a follow-up turn starts the task again.
+ */ function wasStoppedByUser(events) {
+    for(let i = events.length - 1; i >= 0; i--){
+        const type = events[i].type;
+        if (type === 'user_stop') return true;
+        if (type === 'user_message') return false;
+    }
+    return false;
+}
+/**
+ * Details of a pending `waiting` state, from the most recent `status_update`. Not observed in P0
+ * (questions arrived as a normal final answer), kept for the documented confirmation flow.
+ */ function pendingWaiting(events) {
+    const status = lastEventOfType(events, 'status_update')?.status_update;
+    return status?.agent_status === 'waiting' ? status.status_detail ?? {} : undefined;
+}
+
+export { AGENT_EFFORTS, AGENT_PROFILES, MANUS_API_BASE_URL, ManusApiError, ManusClient, createPollQueue, finalAssistantMessage, formatAgentProfile, lastEventOfType, latestAgentStatus, outputAttachments, parseAgentProfile, pendingWaiting, structuredOutput, toMillis, wasStoppedByUser };

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "manus-api",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-beta.1",
+  "description": "Typed client for the Manus API v2",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SukkaW/mcp-manus",
+    "directory": "packages/manus-api"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "keywords": [
+    "manus",
+    "manus-api"
+  ],
+  "author": "SukkaW <https://skk.moe>",
+  "license": "MIT",
+  "dependencies": {
+    "@henrygd/queue": "^1.2.0",
+    "foxts": "^5.9.1"
+  },
+  "devDependencies": {
+    "@swc-node/register": "^1.12.1",
+    "@swc/core": "^1.16.20",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^24.19.2",
+    "bunchee": "^6.12.2",
+    "earl": "^2.0.0",
+    "mocha": "^12.0.3",
+    "nyc": "^18.0.0"
+  },
+  "scripts": {
+    "build": "bunchee --no-sourcemap",
+    "lint": "eslint --format=sukka .",
+    "test": "SWC_NODE_IGNORE_DYNAMIC=1 SWC_NODE_INLINE_SOURCE_MAP=1 nyc mocha",
+    "typecheck": "tsc --build --noEmit"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.