@nestr/mcp 0.1.89 → 0.1.91

package/build/tools/index.js

@@ -123,11 +123,31 @@ const HINT_URL_PATTERNS = [
     },
     // /nests/{id}/posts → nestr_get_comments
     { pattern: /^\/nests\/([^/]+)\/posts$/, tool: "nestr_get_comments", params: (m) => ({ nestId: m[1] }) },
+    // /nests/{id}/files → nestr_get_nest_files
+    { pattern: /^\/nests\/([^/]+)\/files$/, tool: "nestr_get_nest_files", params: (m) => ({ nestId: m[1] }) },
     // /nests/{id}/tensions → nestr_list_tensions
     { pattern: /^\/nests\/([^/]+)\/tensions$/, tool: "nestr_list_tensions", params: (m) => ({ nestId: m[1] }) },
     // /nests/{id} → nestr_get_nest (must be last — catches all /nests/{id} patterns)
     { pattern: /^\/nests\/([^/]+)$/, tool: "nestr_get_nest", params: (m) => ({ nestId: m[1] }) },
 ];
+const HINT_TYPE_TOOL_CALLS = {
+    no_strategy(nest) {
+        const nestId = nest._id;
+        if (!nestId)
+            return null;
+        const labels = nest.labels || [];
+        const isAnchorCircle = labels.includes("circleplus-anchor-circle")
+            || labels.includes("anchor-circle");
+        const fieldKey = isAnchorCircle ? "anchor-circle.strategy" : "circle.strategy";
+        return {
+            tool: "nestr_update_nest",
+            params: {
+                nestId,
+                fields: { [fieldKey]: "<strategy statement — what this circle prioritises now vs. defers>" },
+            },
+        };
+    },
+};
 const HINT_ENDPOINT_TOOL_MAPPINGS = [
     {
         method: "POST",
@@ -262,9 +282,17 @@ export function enrichHints(data) {
         const workspaceId = ancestors?.length ? ancestors[ancestors.length - 1] : undefined;
         record.hints = record.hints.map((hint) => {
             const enriched = { ...hint };
-            // Legacy: single URL → toolCall. Kept for backwards compatibility with
-            // hints that pre-date the endpoints[] payload.
-            if (hint.url) {
+            // Type-based overrides win over URL matching for hints whose URL is
+            // just the nest itself (`/nests/{id}` → nestr_get_nest) and doesn't
+            // point at the actionable follow-up. Registered in HINT_TYPE_TOOL_CALLS.
+            const typeOverride = HINT_TYPE_TOOL_CALLS[hint.type];
+            const overrideCall = typeOverride ? typeOverride(record) : null;
+            if (overrideCall) {
+                enriched.toolCall = overrideCall;
+            }
+            else if (hint.url) {
+                // Legacy: single URL → toolCall. Kept for backwards compatibility with
+                // hints that pre-date the endpoints[] payload.
                 let rawUrl = hint.url;
                 const apiPrefixMatch = rawUrl.match(/^https?:\/\/[^/]+\/api(\/.*)/);
                 if (apiPrefixMatch)
@@ -385,10 +413,15 @@ const coerceIntArray = (schema) => z.preprocess((val) => {
     }
     return val;
 }, schema);
+// Shared description for the sort parameter on list/fetch tools. All of these
+// endpoints honor a `sort` query param server-side (field name, '-' prefix for
+// descending) — the same fields the search `sort:` operator uses.
+const SORT_DESCRIPTION = "Field to sort by, e.g. 'title', 'createdAt', 'updatedAt', 'due', 'order' (manual order). Prefix with '-' for descending, e.g. '-updatedAt'.";
 // Tool input schemas using Zod
 export const schemas = {
     listWorkspaces: z.object({
         search: z.string().optional().describe("Search query to filter workspaces"),
+        sort: z.string().optional().describe(SORT_DESCRIPTION),
         limit: z.number().optional().describe("Max results per page. Omit to see full count in meta.total."),
         page: z.number().optional().describe("Page number (1-indexed) for pagination"),
     }),
@@ -407,6 +440,7 @@ export const schemas = {
     search: z.object({
         workspaceId: z.string().describe("Workspace ID to search in"),
         query: z.string().describe("Search query"),
+        sort: z.string().optional().describe(`${SORT_DESCRIPTION} Takes precedence over sort:/sort-order: operators in the query.`),
         limit: z.number().optional().describe("Max results per page. Omit on first call to see meta.total count."),
         page: z.number().optional().describe("Page number (1-indexed) for pagination"),
         _listTitle: z.string().optional().describe("Short descriptive title for the list UI (e.g., \"Marketing projects\", \"Overdue tasks\"). Omit for default."),
@@ -418,6 +452,7 @@ export const schemas = {
     }),
     getNestChildren: z.object({
         nestId: z.string().describe("Parent nest ID"),
+        sort: z.string().optional().describe(SORT_DESCRIPTION),
         limit: z.number().optional().describe("Max results per page. Omit to see full count in meta.total."),
         page: z.number().optional().describe("Page number for pagination"),
         hints: z.boolean().optional().describe("Include contextual hints on each child nest (default: true). Set to false for large result sets or bulk operations where contextual signals aren't needed."),
@@ -469,17 +504,20 @@ export const schemas = {
     }),
     listCircles: z.object({
         workspaceId: z.string().describe("Workspace ID"),
+        sort: z.string().optional().describe(SORT_DESCRIPTION),
         limit: z.number().optional().describe("Max results per page. Omit to see full count in meta.total."),
         page: z.number().optional().describe("Page number for pagination"),
     }),
     getCircleRoles: z.object({
         workspaceId: z.string().describe("Workspace ID"),
         circleId: z.string().describe("Circle ID"),
+        sort: z.string().optional().describe(SORT_DESCRIPTION),
         limit: z.number().optional().describe("Max results per page. Omit to see full count in meta.total."),
         page: z.number().optional().describe("Page number for pagination"),
     }),
     listRoles: z.object({
         workspaceId: z.string().describe("Workspace ID"),
+        sort: z.string().optional().describe(SORT_DESCRIPTION),
         limit: z.number().optional().describe("Max results per page. Omit to see full count in meta.total."),
         page: z.number().optional().describe("Page number for pagination"),
     }),
@@ -508,6 +546,7 @@ export const schemas = {
     }),
     getProjects: z.object({
         workspaceId: z.string().describe("Workspace ID"),
+        sort: z.string().optional().describe(SORT_DESCRIPTION),
         limit: z.number().optional().describe("Max results per page. Omit to see full count in meta.total."),
         page: z.number().optional().describe("Page number for pagination"),
         _listTitle: z.string().optional().describe("Short descriptive title for the list UI (e.g., \"Engineering projects\"). Omit for default."),
@@ -609,6 +648,16 @@ export const schemas = {
     getMe: z.object({
         fullWorkspaces: z.boolean().optional().describe("Set true to include full workspace details (purpose, labels, governance type, user access roles). Recommended on first call to establish workspace context."),
     }),
+    // Current user's cross-workspace activity (requires OAuth token)
+    myActivity: z.object({
+        limit: z.number().optional().describe("Max activity items to return (default 50, max 200)."),
+        withUser: z.string().optional().describe("Scope DM considerations to the conversation with this user id. Agent internal considerations from direct-message runs are redacted to an anonymous marker unless you name that conversation's counterpart here."),
+    }),
+    // Another user's cross-workspace activity (requires OAuth token)
+    userActivity: z.object({
+        userId: z.string().describe("The user whose activity to fetch."),
+        limit: z.number().optional().describe("Max activity items to return (default 50, max 200)."),
+    }),
     // User tension tools (requires OAuth token)
     listMyTensions: z.object({
         context: z.string().optional().describe("Optional context filter (e.g., workspace ID or circle ID)"),
@@ -640,8 +689,10 @@ export const schemas = {
     listTensions: z.object({
         nestId: z.string().describe("ID of the circle or role to list tensions for"),
         search: z.string().optional().describe("Search query to filter tensions"),
+        sort: z.string().optional().describe(SORT_DESCRIPTION),
         limit: z.number().optional().describe("Max results to return"),
-        order: z.string().optional().describe("Sort order (e.g., 'createdAt', '-createdAt')"),
+        page: z.number().optional().describe("Page number for pagination"),
+        order: z.string().optional().describe("Deprecated alias of sort"),
     }),
     updateTension: z.object({
         nestId: z.string().describe("ID of the circle or role the tension belongs to"),
@@ -759,6 +810,46 @@ export const schemas = {
         maxImages: coerceFromJson(z.number().int().positive().optional()).describe("Help-article mode only. Cap on how many screenshots the default selection attaches (the first N content images in document order). Default 3, max 6. Ignored when imageIndexes is provided."),
     }).refine((v) => Boolean(v.topic) || Boolean(v.search), { message: "Provide either `topic` or `search`." }),
     diagnose: z.object({}).describe("No arguments — diagnose reads session state from the server."),
+    // Connector tools (registration is workspace-admin only)
+    listConnectors: z.object({
+        workspaceId: z.string().describe("Workspace ID whose connector catalog to list"),
+    }),
+    registerConnector: z.object({
+        workspaceId: z.string().describe("Workspace ID to register the connector in"),
+        type: z.enum(["mcp", "cli", "api"]).describe("Transport: 'mcp' (MCP server over a url), 'api' (REST endpoint over a url), or 'cli' (a command)"),
+        name: z.string().describe("Unique connector name within the workspace catalog"),
+        config: coerceFromJson(z.record(z.unknown())).optional().describe("Per-type transport config, no secret. mcp/api need a url (e.g., { url: 'https://...' }); cli needs a command (e.g., { command: 'some-cli' }). Optional non-secret headers go under headers."),
+        capabilities: coerceFromJson(z.record(z.unknown())).optional().describe("Capability descriptor: { discover: boolean, tools: [{ name, description, inputSchema }] }. discover:true lets the connector self-describe its tools at runtime."),
+        exposure: coerceFromJson(z.record(z.unknown())).optional().describe("Exposure policy deciding which owners may bind: { userAgent: boolean, domainGated: boolean }. Set domainGated:true to allow binding to a role's domain."),
+        authStrategy: z.enum(["secret", "oauth2"]).optional().describe("How a principal connects: 'secret' (a one-time secret captured via the Connect button) or 'oauth2'. The agent never sees the secret."),
+    }),
+    bindConnector: z.object({
+        workspaceId: z.string().describe("Workspace ID the connector and owner belong to"),
+        connectorId: z.string().describe("ID of an enabled connector from nestr_list_connectors"),
+        ownerType: z.enum(["user", "agent", "workspace", "role-domain"]).describe("Owner type. 'role-domain' binds the connector to a role's domain so the role can use it and a credentials field is materialised on the domain."),
+        ownerId: z.string().describe("Owner ID. user/agent: the user ID. workspace: the workspace ID. role-domain: the domain nest ID."),
+    }),
+    // File attachments (a comment id works as the nestId — files are keyed by nestId)
+    getNestFiles: z.object({
+        nestId: z.string().describe("Nest or comment ID whose file attachments to list"),
+    }),
+    readFile: z.object({
+        nestId: z.string().describe("Nest or comment ID the file is attached to"),
+        fileId: z.string().describe("File ID from nestr_get_nest_files"),
+    }),
+    uploadFile: z.object({
+        nestId: z.string().describe("Nest or comment ID to attach the file to"),
+        name: z.string().describe('File name including extension (e.g. "notes.md", "data.csv")'),
+        contentType: z.string().describe('MIME type of the file (e.g. "text/markdown", "text/csv", "image/png")'),
+        content: z.string().optional().describe("File content as UTF-8 text. Use for text-native files you author directly (.md, .txt, .csv, .json, .html, .svg, code). Stored verbatim. Provide this OR dataBase64, not both."),
+        dataBase64: z.string().optional().describe("File bytes, base64-encoded. Use for binary content you already hold as base64. Provide this OR content, not both."),
+    }).refine((v) => (v.content !== undefined) !== (v.dataBase64 !== undefined), {
+        message: "Provide exactly one of content (UTF-8 text) or dataBase64 (base64 bytes).",
+    }),
+    deleteFile: z.object({
+        nestId: z.string().describe("Nest or comment ID the file is attached to"),
+        fileId: z.string().describe("File ID from nestr_get_nest_files"),
+    }),
 };
 // Tool annotations for MCP - hints for clients on tool behavior
 const readOnly = { annotations: { readOnlyHint: true, destructiveHint: false } };
@@ -797,6 +888,7 @@ export const toolDefinitions = [
             type: "object",
             properties: {
                 search: { type: "string", description: "Search query to filter workspaces" },
+                sort: { type: "string", description: SORT_DESCRIPTION },
                 limit: { type: "number", description: "Omit on first call to see meta.total count" },
                 page: { type: "number", description: "Page number (1-indexed) for pagination" },
                 stripDescription: { type: "boolean", description: "Set true to strip description fields from response, significantly reducing size. Ideal for bulk/index operations." },
@@ -863,6 +955,7 @@ export const toolDefinitions = [
             properties: {
                 workspaceId: { type: "string", description: "Workspace ID to search in" },
                 query: { type: "string", description: "Search query with optional operators (e.g., 'label:role', 'assignee:me completed:false')" },
+                sort: { type: "string", description: `${SORT_DESCRIPTION} Takes precedence over sort:/sort-order: operators in the query.` },
                 limit: { type: "number", description: "Max results per page. Do NOT set on first call - let API return default with meta.total count showing total matches." },
                 page: { type: "number", description: "Page number (1-indexed) for fetching additional pages" },
                 stripDescription: { type: "boolean", description: "Set true to strip description fields from response, significantly reducing size. Ideal for bulk/index operations." },
@@ -896,6 +989,7 @@ export const toolDefinitions = [
             type: "object",
             properties: {
                 nestId: { type: "string", description: "Parent nest ID" },
+                sort: { type: "string", description: SORT_DESCRIPTION },
                 limit: { type: "number", description: "Omit on first call to see meta.total count" },
                 page: { type: "number", description: "Page number (1-indexed)" },
                 hints: { type: "boolean", description: "Include contextual hints (default: true). Set to false for large result sets or bulk operations." },
@@ -1074,6 +1168,7 @@ export const toolDefinitions = [
             type: "object",
             properties: {
                 workspaceId: { type: "string", description: "Workspace ID" },
+                sort: { type: "string", description: SORT_DESCRIPTION },
                 limit: { type: "number", description: "Omit on first call to see meta.total count" },
                 page: { type: "number", description: "Page number (1-indexed)" },
                 stripDescription: { type: "boolean", description: "Set true to strip description fields from response, significantly reducing size. Ideal for large workspaces." },
@@ -1090,6 +1185,7 @@ export const toolDefinitions = [
             properties: {
                 workspaceId: { type: "string", description: "Workspace ID" },
                 circleId: { type: "string", description: "Circle ID" },
+                sort: { type: "string", description: SORT_DESCRIPTION },
                 limit: { type: "number", description: "Omit on first call to see meta.total count" },
                 page: { type: "number", description: "Page number (1-indexed)" },
                 stripDescription: { type: "boolean", description: "Set true to strip description fields from response, significantly reducing size. Ideal for large circles." },
@@ -1105,6 +1201,7 @@ export const toolDefinitions = [
             type: "object",
             properties: {
                 workspaceId: { type: "string", description: "Workspace ID" },
+                sort: { type: "string", description: SORT_DESCRIPTION },
                 limit: { type: "number", description: "Omit on first call to see meta.total count" },
                 page: { type: "number", description: "Page number (1-indexed)" },
                 stripDescription: { type: "boolean", description: "Set true to strip description fields from response, significantly reducing size. Ideal for large workspaces." },
@@ -1179,6 +1276,7 @@ export const toolDefinitions = [
             type: "object",
             properties: {
                 workspaceId: { type: "string", description: "Workspace ID" },
+                sort: { type: "string", description: SORT_DESCRIPTION },
                 limit: { type: "number", description: "Omit on first call to see meta.total count" },
                 page: { type: "number", description: "Page number (1-indexed)" },
                 stripDescription: { type: "boolean", description: "Set true to strip description fields from response, significantly reducing size. Ideal for large workspaces." },
@@ -1444,6 +1542,33 @@ export const toolDefinitions = [
         _meta: completableListUi,
         ...readOnly,
     },
+    // Current user's cross-workspace activity (requires OAuth token)
+    {
+        name: "nestr_my_activity",
+        description: "The caller's own activity across ALL their workspaces, newest first (gated by workspace membership and the token's scope). Not scoped to a project or a single nest — it's everything you've done. For an agent, this is how it sees what it has done: past considerations (with the tools used and the outcome), comments, governance changes, and other actions. Agent internal considerations from direct-message runs are redacted to an anonymous marker unless you pass withUser with that conversation's counterpart. Auth: OAuth only (user-scoped — workspace API keys lack user identity). On auth failure call nestr_diagnose.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: { type: "number", description: "Max activity items to return (default 50, max 200)." },
+                withUser: { type: "string", description: "Scope DM considerations to the conversation with this user id. Agent internal considerations from direct-message runs are redacted to an anonymous marker unless you name that conversation's counterpart here." },
+            },
+        },
+        ...readOnly,
+    },
+    // Another user's cross-workspace activity (requires OAuth token)
+    {
+        name: "nestr_user_activity",
+        description: "Another user's activity across the workspaces you share with them, newest first. Lets an agent see what a colleague or another agent has done: their past considerations (with the tools used and the outcome), comments, governance changes, and other actions. Agent internal considerations from direct-message runs show their substance only when you are a participant of that conversation, otherwise an anonymous marker. Auth: OAuth only (user-scoped — workspace API keys lack user identity). On auth failure call nestr_diagnose.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                userId: { type: "string", description: "The user whose activity to fetch." },
+                limit: { type: "number", description: "Max activity items to return (default 50, max 200)." },
+            },
+            required: ["userId"],
+        },
+        ...readOnly,
+    },
     // Label management
     {
         name: "nestr_add_label",
@@ -1601,8 +1726,12 @@ export const toolDefinitions = [
             properties: {
                 nestId: { type: "string", description: "ID of the circle or role to list tensions for" },
                 search: { type: "string", description: "Search query to filter tensions" },
+                sort: { type: "string", description: SORT_DESCRIPTION },
                 limit: { type: "number", description: "Max results to return" },
-                order: { type: "string", description: "Sort order (e.g., 'createdAt', '-createdAt')" },
+                page: { type: "number", description: "Page number (1-indexed)" },
+                // The legacy `order` alias is deliberately not advertised — the Zod
+                // schema still accepts it so existing callers keep working, but new
+                // clients should only learn the canonical `sort` param.
             },
             required: ["nestId"],
         },
@@ -1856,6 +1985,129 @@ export const toolDefinitions = [
         },
         ...destructive,
     },
+    {
+        name: "nestr_list_connectors",
+        description: "List the workspace's connector catalog: the mcp / cli / api templates an admin has registered. Each entry holds no secret and shows its type, name, authStrategy, config, capabilities, exposure ({ userAgent, domainGated }) and whether it is enabled. Typical flow: register a connector, then bind it to a role's domain with nestr_bind_connector, then a human or agent connects the account via the credentials field's Connect button (the secret is captured out-of-band, never by the agent). Auth: any valid token can list.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: { type: "string", description: "Workspace ID whose connector catalog to list" },
+            },
+            required: ["workspaceId"],
+        },
+        ...readOnly,
+    },
+    {
+        name: "nestr_register_connector",
+        description: "Register a connector in the workspace catalog: a reusable mcp / cli / api template that holds no secret. Workspace-admin only. A non-admin caller gets AUTH_SCOPE_INSUFFICIENT (call nestr_diagnose on any auth error). Provide type ('mcp' or 'api' need a url in config; 'cli' needs a command) and a unique name; optionally capabilities, exposure ({ userAgent, domainGated }), and authStrategy ('secret' or 'oauth2'). This only creates the template. Typical flow: register here, then bind it to a role's domain with nestr_bind_connector, then a human or agent connects the account via the credentials field's Connect button. The secret is captured out-of-band through that button, never by the agent.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: { type: "string", description: "Workspace ID to register the connector in" },
+                type: {
+                    type: "string",
+                    enum: ["mcp", "cli", "api"],
+                    description: "Transport: 'mcp' (MCP server over a url), 'api' (REST endpoint over a url), or 'cli' (a command)",
+                },
+                name: { type: "string", description: "Unique connector name within the workspace catalog" },
+                config: {
+                    type: "object",
+                    description: "Per-type transport config, no secret. mcp/api need a url (e.g., { url: 'https://...' }); cli needs a command (e.g., { command: 'some-cli' }). Optional non-secret headers go under headers.",
+                },
+                capabilities: {
+                    type: "object",
+                    description: "Capability descriptor: { discover: boolean, tools: [{ name, description, inputSchema }] }. discover:true lets the connector self-describe its tools at runtime.",
+                },
+                exposure: {
+                    type: "object",
+                    description: "Exposure policy deciding which owners may bind: { userAgent: boolean, domainGated: boolean }. Set domainGated:true to allow binding to a role's domain.",
+                },
+                authStrategy: {
+                    type: "string",
+                    enum: ["secret", "oauth2"],
+                    description: "How a principal connects: 'secret' (a one-time secret captured via the Connect button) or 'oauth2'. The agent never sees the secret.",
+                },
+            },
+            required: ["workspaceId", "type", "name"],
+        },
+        ...mutating,
+    },
+    {
+        name: "nestr_bind_connector",
+        description: "Bind a registered connector to an owner so that owner can use it. Owner types: 'user' or 'agent' (ownerId is the user ID), 'workspace' (ownerId is the workspace ID), or 'role-domain' (ownerId is the domain nest ID). A 'role-domain' owner also materialises a credentials field on the domain nest, so the role can use the connector and the Connect button renders there; the response then includes credentialsField { domainId, fieldId, fieldCode }. After binding, a human or agent connects the account via that Connect button. The secret is captured out-of-band and is never seen by the agent. Workspace-admin only: a non-admin caller gets AUTH_SCOPE_INSUFFICIENT. The connector must already be registered (nestr_register_connector) and enabled.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: { type: "string", description: "Workspace ID the connector and owner belong to" },
+                connectorId: { type: "string", description: "ID of an enabled connector from nestr_list_connectors" },
+                ownerType: {
+                    type: "string",
+                    enum: ["user", "agent", "workspace", "role-domain"],
+                    description: "Owner type. 'role-domain' binds the connector to a role's domain so the role can use it and a credentials field is materialised on the domain.",
+                },
+                ownerId: {
+                    type: "string",
+                    description: "Owner ID. user/agent: the user ID. workspace: the workspace ID. role-domain: the domain nest ID.",
+                },
+            },
+            required: ["workspaceId", "connectorId", "ownerType", "ownerId"],
+        },
+        ...mutating,
+    },
+    {
+        name: "nestr_get_nest_files",
+        description: "List a nest's file attachments. A comment ID works too — files are keyed by nestId, so pass a comment ID to see files attached to that comment. Returns each file's id, name, contentType and size. Use nestr_read_file with a returned id to read one (images come back as viewable image content). Auth: any valid token with access to the nest.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                nestId: { type: "string", description: "Nest or comment ID whose file attachments to list" },
+            },
+            required: ["nestId"],
+        },
+        ...readOnly,
+    },
+    {
+        name: "nestr_read_file",
+        description: "Read a single file attachment on a nest (or comment). Branches on contentType: images (image/*) return as viewable image content so you can see them (very large images return metadata only); JSON and text (application/json, text/*) return as decoded UTF-8 text (large text is truncated); PDFs and other types return their metadata only (cannot be inlined yet). Get file ids from nestr_get_nest_files. A comment ID works as the nestId. Auth: any valid token with access to the nest.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                nestId: { type: "string", description: "Nest or comment ID the file is attached to" },
+                fileId: { type: "string", description: "File ID from nestr_get_nest_files" },
+            },
+            required: ["nestId", "fileId"],
+        },
+        ...readOnly,
+    },
+    {
+        name: "nestr_upload_file",
+        description: "Upload a file and attach it to a nest (or comment; files are keyed by nestId, so a comment ID attaches the file to that comment). Provide the file one of two ways: content (UTF-8 text, for text-native files you author directly such as .md, .csv, .json, .html, .svg, or code) or dataBase64 (base64-encoded bytes you already have). Any content type is accepted; the upload is rejected if it exceeds the server's maximum size (default 10MB). Returns the new file's descriptor (id, name, contentType, size). Auth: a token with write access to the nest.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                nestId: { type: "string", description: "Nest or comment ID to attach the file to" },
+                name: { type: "string", description: 'File name including extension (e.g. "notes.md", "data.csv")' },
+                contentType: { type: "string", description: 'MIME type (e.g. "text/markdown", "text/csv", "image/png")' },
+                content: { type: "string", description: "File content as UTF-8 text (for text-native files: .md, .txt, .csv, .json, .html, .svg, code). Stored verbatim. Provide this OR dataBase64." },
+                dataBase64: { type: "string", description: "File bytes, base64-encoded. Provide this OR content." },
+            },
+            required: ["nestId", "name", "contentType"],
+        },
+        ...mutating,
+    },
+    {
+        name: "nestr_delete_file",
+        description: "Delete a file attachment from a nest (or comment). Get the file id from nestr_get_nest_files. A comment ID works as the nestId. This permanently removes the file. Auth: a token with delete access to the nest.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                nestId: { type: "string", description: "Nest or comment ID the file is attached to" },
+                fileId: { type: "string", description: "File ID from nestr_get_nest_files" },
+            },
+            required: ["nestId", "fileId"],
+        },
+        ...destructive,
+    },
 ];
 // Strip description fields from nest objects in response data
 export function stripDescriptionFields(data) {
@@ -1907,6 +2159,42 @@ export function unescapeRichTextFields(args) {
     }
     return changed ? result : args;
 }
+/**
+ * Extract sort:/sort-order:/limit: directives from a search query string.
+ *
+ * The REST API only honors sorting and limits via the `sort`/`limit` query
+ * params — these operators inside the search string are dropped from free-text
+ * matching and otherwise ignored. Translating them here keeps the documented
+ * search syntax (see nestr_help('search')) working. The query string itself is
+ * sent unmodified: the server strips operator terms from text matching anyway.
+ *
+ * First occurrence wins for each directive, matching the server-side parsing
+ * of these operators elsewhere in Nestr.
+ */
+export function extractSearchDirectives(query) {
+    let sortField;
+    let sortOrder;
+    let limit;
+    for (const term of query.split(/\s+/)) {
+        const lower = term.toLowerCase();
+        if (sortField === undefined && lower.startsWith("sort:")) {
+            sortField = term.slice("sort:".length);
+        }
+        else if (sortOrder === undefined && lower.startsWith("sort-order:")) {
+            sortOrder = lower.slice("sort-order:".length);
+        }
+        else if (limit === undefined && lower.startsWith("limit:")) {
+            const parsed = Number.parseInt(lower.slice("limit:".length), 10);
+            if (!Number.isNaN(parsed) && parsed > 0)
+                limit = parsed;
+        }
+    }
+    let sort;
+    if (sortField) {
+        sort = sortOrder === "desc" && !sortField.startsWith("-") ? `-${sortField}` : sortField;
+    }
+    return { sort, limit };
+}
 export async function handleToolCall(client, name, args, context) {
     const sanitizedArgs = unescapeRichTextFields(args);
     const shouldStripDescription = sanitizedArgs.stripDescription === true;
@@ -2114,6 +2402,7 @@ async function _handleToolCall(client, name, args, context) {
                 const parsed = schemas.listWorkspaces.parse(args);
                 const workspaces = await client.listWorkspaces({
                     search: parsed.search,
+                    sort: parsed.sort,
                     limit: parsed.limit,
                     page: parsed.page,
                     cleanText: true,
@@ -2142,7 +2431,13 @@ async function _handleToolCall(client, name, args, context) {
             }
             case "nestr_search": {
                 const parsed = schemas.search.parse(args);
-                const results = await client.searchWorkspace(parsed.workspaceId, parsed.query, { limit: parsed.limit, page: parsed.page, cleanText: true });
+                const directives = extractSearchDirectives(parsed.query);
+                const results = await client.searchWorkspace(parsed.workspaceId, parsed.query, {
+                    sort: parsed.sort ?? directives.sort,
+                    limit: parsed.limit ?? directives.limit,
+                    page: parsed.page,
+                    cleanText: true,
+                });
                 return formatResult(completableResponse(compactResponse(results), "search", parsed._listTitle || `Search: ${parsed.query}`));
             }
             case "nestr_get_nest": {
@@ -2157,6 +2452,7 @@ async function _handleToolCall(client, name, args, context) {
             case "nestr_get_nest_children": {
                 const parsed = schemas.getNestChildren.parse(args);
                 const children = await client.getNestChildren(parsed.nestId, {
+                    sort: parsed.sort,
                     limit: parsed.limit,
                     page: parsed.page,
                     cleanText: true,
@@ -2275,6 +2571,7 @@ async function _handleToolCall(client, name, args, context) {
             case "nestr_list_circles": {
                 const parsed = schemas.listCircles.parse(args);
                 const circles = await client.listCircles(parsed.workspaceId, {
+                    sort: parsed.sort,
                     limit: parsed.limit,
                     page: parsed.page,
                     cleanText: true,
@@ -2283,12 +2580,13 @@ async function _handleToolCall(client, name, args, context) {
             }
             case "nestr_get_circle_roles": {
                 const parsed = schemas.getCircleRoles.parse(args);
-                const roles = await client.getCircleRoles(parsed.workspaceId, parsed.circleId, { limit: parsed.limit, page: parsed.page, cleanText: true });
+                const roles = await client.getCircleRoles(parsed.workspaceId, parsed.circleId, { sort: parsed.sort, limit: parsed.limit, page: parsed.page, cleanText: true });
                 return formatResult(compactResponse(roles, "role"));
             }
             case "nestr_list_roles": {
                 const parsed = schemas.listRoles.parse(args);
                 const roles = await client.listRoles(parsed.workspaceId, {
+                    sort: parsed.sort,
                     limit: parsed.limit,
                     page: parsed.page,
                     cleanText: true,
@@ -2331,6 +2629,7 @@ async function _handleToolCall(client, name, args, context) {
             case "nestr_get_projects": {
                 const parsed = schemas.getProjects.parse(args);
                 const projects = await client.getWorkspaceProjects(parsed.workspaceId, {
+                    sort: parsed.sort,
                     limit: parsed.limit,
                     page: parsed.page,
                     cleanText: true,
@@ -2490,6 +2789,21 @@ async function _handleToolCall(client, name, args, context) {
                 const items = await client.getDailyPlan();
                 return formatResult(completableResponse(compactResponse(items), "daily-plan", "Daily Plan"));
             }
+            case "nestr_my_activity": {
+                const parsed = schemas.myActivity.parse(args);
+                const activity = await client.getMyActivity({
+                    limit: parsed.limit,
+                    withUser: parsed.withUser,
+                });
+                return formatResult({ count: activity.length, activity });
+            }
+            case "nestr_user_activity": {
+                const parsed = schemas.userActivity.parse(args);
+                const activity = await client.getUserActivity(parsed.userId, {
+                    limit: parsed.limit,
+                });
+                return formatResult({ count: activity.length, activity });
+            }
             // Current user identity and workspace context
             case "nestr_get_me": {
                 const parsed = schemas.getMe.parse(args);
@@ -2610,7 +2924,14 @@ async function _handleToolCall(client, name, args, context) {
             }
             case "nestr_list_tensions": {
                 const parsed = schemas.listTensions.parse(args);
-                const tensions = await client.listTensions(parsed.nestId, parsed.search, { limit: parsed.limit, order: parsed.order, cleanText: true });
+                const tensions = await client.listTensions(parsed.nestId, parsed.search, {
+                    // `order` is the legacy name for this option — it was never honored
+                    // by the API (which reads `sort`), so route both through sort.
+                    sort: parsed.sort ?? parsed.order,
+                    limit: parsed.limit,
+                    page: parsed.page,
+                    cleanText: true,
+                });
                 return formatResult(compactResponse(enrichHints(tensions)));
             }
             case "nestr_update_tension": {
@@ -2733,6 +3054,127 @@ async function _handleToolCall(client, name, args, context) {
                 const result = await client.removeGraphLink(parsed.nestId, parsed.relation, parsed.targetId);
                 return formatResult({ message: "Graph link removed" });
             }
+            // Connector tools
+            case "nestr_list_connectors": {
+                const parsed = schemas.listConnectors.parse(args);
+                const connectors = await client.listConnectors(parsed.workspaceId);
+                return formatResult(connectors);
+            }
+            case "nestr_register_connector": {
+                const parsed = schemas.registerConnector.parse(args);
+                const connector = await client.registerConnector(parsed.workspaceId, {
+                    type: parsed.type,
+                    name: parsed.name,
+                    config: parsed.config,
+                    capabilities: parsed.capabilities,
+                    exposure: parsed.exposure,
+                    authStrategy: parsed.authStrategy,
+                });
+                return formatResult({
+                    message: "Connector registered. Next, bind it to an owner with nestr_bind_connector (e.g. a role's domain), then a human or agent connects the account via the credentials field's Connect button.",
+                    connector,
+                });
+            }
+            case "nestr_bind_connector": {
+                const parsed = schemas.bindConnector.parse(args);
+                const connection = await client.bindConnector(parsed.workspaceId, {
+                    connectorId: parsed.connectorId,
+                    owner: { type: parsed.ownerType, id: parsed.ownerId },
+                });
+                // For a role-domain binding the API materialises a credentials field on
+                // the domain; surface that explicitly so the caller knows the Connect
+                // button now renders there and the secret is captured out-of-band.
+                const message = parsed.ownerType === "role-domain"
+                    ? "Connector bound to the role's domain. A credentials field was materialised on the domain (see credentialsField) so the role can use the connector and the Connect button renders. A human or agent now connects the account via that button; the secret is captured out-of-band and never by the agent."
+                    : "Connector bound to the owner. The owner now connects the account out-of-band; the secret is never seen by the agent.";
+                return formatResult({ message, connection });
+            }
+            case "nestr_get_nest_files": {
+                const parsed = schemas.getNestFiles.parse(args);
+                const files = await client.getNestFiles(parsed.nestId);
+                if (files.length === 0) {
+                    return { content: [{ type: "text", text: `No file attachments on ${parsed.nestId}.` }] };
+                }
+                const lines = files.map((f) => `- ${f.id} — ${f.name} (${f.contentType}, ${formatBytes(f.size)})`);
+                const text = `${files.length} file${files.length === 1 ? "" : "s"} attached to ${parsed.nestId}. Read one with nestr_read_file({ nestId: "${parsed.nestId}", fileId: "<id>" }).\n\n${lines.join("\n")}`;
+                return { content: [{ type: "text", text }] };
+            }
+            case "nestr_read_file": {
+                const parsed = schemas.readFile.parse(args);
+                const file = await client.getNestFile(parsed.nestId, parsed.fileId);
+                const contentType = file.contentType || "application/octet-stream";
+                // Images: return as a viewable image content item (mirrors nestr_help).
+                // Guard the size first — an image over MAX_IMAGE_INLINE_BYTES exceeds the
+                // per-image limit of the model API the agent forwards it to, so inlining
+                // the base64 would just make that call fail. Degrade to a metadata note.
+                if (contentType.startsWith("image/")) {
+                    // Not `??`: size can legitimately be 0 when a legacy file's metadata was
+                    // lost (the API descriptor falls back to 0), and there we want the real
+                    // byte length so the cap still applies. `> 0` recomputes on a zero/missing
+                    // size; trusting a 0 would skip the guard on a large legacy image.
+                    const imageBytes = file.size > 0 ? file.size : Buffer.byteLength(file.dataBase64, "base64");
+                    if (imageBytes > MAX_IMAGE_INLINE_BYTES) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `File: ${file.name}\nContent type: ${contentType}\nSize: ${formatBytes(imageBytes)}\n\nThis image is too large to inline (limit ${formatBytes(MAX_IMAGE_INLINE_BYTES)}). Download it directly to view the content.`,
+                                },
+                            ],
+                        };
+                    }
+                    return {
+                        content: [
+                            { type: "text", text: `File: ${file.name} (${contentType}, ${formatBytes(file.size)})` },
+                            { type: "image", data: file.dataBase64, mimeType: contentType },
+                        ],
+                    };
+                }
+                // JSON / text / CSV: decode to UTF-8 and return as a text block.
+                if (contentType.startsWith("text/") ||
+                    contentType.startsWith("application/json")) {
+                    const decoded = Buffer.from(file.dataBase64, "base64").toString("utf-8");
+                    const { text: body, truncated } = capText(decoded);
+                    const note = truncated
+                        ? `\n\n_(truncated — file is ${formatBytes(file.size)}; showing the first ${MAX_TEXT_FILE_CHARS} characters)_`
+                        : "";
+                    return {
+                        content: [
+                            { type: "text", text: `File: ${file.name} (${contentType}, ${formatBytes(file.size)})\n\n${body}${note}` },
+                        ],
+                    };
+                }
+                // PDFs and everything else: metadata only. The ToolResult content type
+                // supports text + image blocks, so a non-image binary can't be inlined yet.
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `File: ${file.name}\nContent type: ${contentType}\nSize: ${formatBytes(file.size)}\n\nThis file type can't be inlined yet — only images (returned as viewable image content) and text/JSON (returned as decoded text) are supported.`,
+                        },
+                    ],
+                };
+            }
+            case "nestr_upload_file": {
+                const parsed = schemas.uploadFile.parse(args);
+                // The REST API takes base64 bytes; base64-encode the text convenience here
+                // so the model can hand over content it authored without encoding it itself.
+                const dataBase64 = parsed.dataBase64 ?? Buffer.from(parsed.content ?? "", "utf-8").toString("base64");
+                const file = await client.createNestFile(parsed.nestId, {
+                    name: parsed.name,
+                    contentType: parsed.contentType,
+                    dataBase64,
+                });
+                return formatResult({
+                    message: `Uploaded ${file.name} (${formatBytes(file.size)}) to ${parsed.nestId}.`,
+                    file,
+                });
+            }
+            case "nestr_delete_file": {
+                const parsed = schemas.deleteFile.parse(args);
+                await client.deleteNestFile(parsed.nestId, parsed.fileId);
+                return formatResult({ message: `Deleted file ${parsed.fileId} from ${parsed.nestId}.` });
+            }
             default:
                 return formatError({
                     error: true,
@@ -2801,6 +3243,34 @@ function buildDiagnoseHint(snapshot) {
     }
     return "Server-side state looks healthy. If a tool is failing, include sessionCorrelationId in the bug report.";
 }
+// Cap on decoded text-file content returned by nestr_read_file, to bound token
+// cost on large files. ~200 KB of characters.
+const MAX_TEXT_FILE_CHARS = 200_000;
+/** Truncate decoded text to MAX_TEXT_FILE_CHARS, flagging whether it was cut. */
+function capText(text) {
+    if (text.length <= MAX_TEXT_FILE_CHARS)
+        return { text, truncated: false };
+    return { text: text.slice(0, MAX_TEXT_FILE_CHARS), truncated: true };
+}
+// Cap on an image returned inline by nestr_read_file. Above this the base64 blob
+// exceeds the ~5MB-per-image limit of the model API the agent forwards it to, so
+// we return metadata instead of an image block that call would reject.
+const MAX_IMAGE_INLINE_BYTES = 5 * 1024 * 1024;
+/** Human-readable byte size (e.g. "12.3 KB"). */
+function formatBytes(bytes) {
+    if (!Number.isFinite(bytes) || bytes < 0)
+        return "unknown size";
+    if (bytes < 1024)
+        return `${bytes} B`;
+    const units = ["KB", "MB", "GB"];
+    let size = bytes / 1024;
+    let unit = 0;
+    while (size >= 1024 && unit < units.length - 1) {
+        size /= 1024;
+        unit++;
+    }
+    return `${size.toFixed(1)} ${units[unit]}`;
+}
 function formatResult(data) {
     return {
         content: [