@stratusagent/agents 0.13.5 → 0.13.7

package/dist/index.d.ts

@@ -7,7 +7,8 @@ export { type AgentRouteRule, type AgentRouter, createAgentRouter, createAgentTe
 export { MEMORY_TOOL_NAME, createRememberTool, RECALL_TOOL_NAME, createRecallTool, FORGET_TOOL_NAME, createForgetTool, PIN_TOOL_NAME, createPinTool, type MemoryToolOptions, } from './tools/memory.ts';
 export { DELEGATE_TOOL_NAME, DELEGATED_BY_METADATA_KEY, ROOT_SESSION_ID_METADATA_KEY, DELEGATION_DEPTH_METADATA_KEY, DELEGATED_SESSION_ID_MARKER, DEFAULT_MAX_DELEGATION_DEPTH, isDelegatedSession, delegatingSessionIdOf, outstandingDelegationFor, withoutDelegation, type DelegateDispatch, type DelegateToolOptions, createDelegateTool, } from './tools/delegate.ts';
 export { SCHEDULE_EVERY_TOOL_NAME, SCHEDULE_AT_TOOL_NAME, SCHEDULE_LIST_TOOL_NAME, SCHEDULE_CANCEL_TOOL_NAME, createScheduleTools, } from './tools/schedule.ts';
-export { MESSAGE_SEND_TOOL_NAME, type OutboundMessenger, createMessageSendTool, type DefaultThreadResolver, MESSAGE_READ_TOOL_NAME, MESSAGE_READ_MAX_LIMIT, MESSAGE_READ_TEXT_BUDGET, type ConversationReader, type ConversationReadRefusal, createMessageReadTool, directMessageReadRefusal, } from './tools/message.ts';
+export { MESSAGE_SEND_TOOL_NAME, type OutboundMessenger, createMessageSendTool, type DefaultThreadResolver, MESSAGE_READ_TOOL_NAME, MESSAGE_READ_MAX_LIMIT, MESSAGE_READ_BOOKMARK_BUDGET, MESSAGE_READ_TEXT_BUDGET, type ConversationReader, type ConversationReadRefusal, createMessageReadTool, directMessageReadRefusal, } from './tools/message.ts';
+export { CHANNEL_CREATE_TOOL_NAME, type ConversationCreator, createChannelCreateTool, } from './tools/channel.ts';
 export { CREDENTIAL_REQUEST_TOOL_NAME, type CredentialRequester, createCredentialRequestTool, } from './tools/credentials.ts';
 export { GATEWAY_ONLY_TOOL_NAMES } from './tools/gateway-only.ts';
 export { loadStratusSkill, STRATUS_SKILL_PATH } from './builtin-skills.ts';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EACd,oBAAoB,EACpB,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,KAAK,gBAAgB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEjE,OAAO,EACL,iBAAiB,EACjB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,SAAS,EACT,UAAU,GACX,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,4BAA4B,EAC5B,8BAA8B,EAC9B,KAAK,mBAAmB,EACxB,kBAAkB,EAClB,KAAK,4BAA4B,EACjC,KAAK,eAAe,EACpB,qBAAqB,EACrB,KAAK,cAAc,EACnB,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,KAAK,mBAAmB,EACxB,oBAAoB,EACpB,gBAAgB,EAChB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,aAAa,EACb,mBAAmB,EACnB,aAAa,EACb,eAAe,EACf,wBAAwB,EACxB,2BAA2B,EAC3B,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,iBAAiB,EACjB,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,KAAK,iBAAiB,GACvB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,4BAA4B,EAC5B,6BAA6B,EAC7B,2BAA2B,EAC3B,4BAA4B,EAC5B,kBAAkB,EAClB,qBAAqB,EACrB,wBAAwB,EACxB,iBAAiB,EACjB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,kBAAkB,GACnB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,uBAAuB,EACvB,yBAAyB,EACzB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,sBAAsB,EACtB,KAAK,iBAAiB,EACtB,qBAAqB,EACrB,KAAK,qBAAqB,EAC1B,sBAAsB,EACtB,sBAAsB,EACtB,wBAAwB,EACxB,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,4BAA4B,EAC5B,KAAK,mBAAmB,EACxB,2BAA2B,GAC5B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EACd,oBAAoB,EACpB,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,KAAK,gBAAgB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEjE,OAAO,EACL,iBAAiB,EACjB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,SAAS,EACT,UAAU,GACX,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,4BAA4B,EAC5B,8BAA8B,EAC9B,KAAK,mBAAmB,EACxB,kBAAkB,EAClB,KAAK,4BAA4B,EACjC,KAAK,eAAe,EACpB,qBAAqB,EACrB,KAAK,cAAc,EACnB,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,KAAK,mBAAmB,EACxB,oBAAoB,EACpB,gBAAgB,EAChB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,aAAa,EACb,mBAAmB,EACnB,aAAa,EACb,eAAe,EACf,wBAAwB,EACxB,2BAA2B,EAC3B,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,iBAAiB,EACjB,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,KAAK,iBAAiB,GACvB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,4BAA4B,EAC5B,6BAA6B,EAC7B,2BAA2B,EAC3B,4BAA4B,EAC5B,kBAAkB,EAClB,qBAAqB,EACrB,wBAAwB,EACxB,iBAAiB,EACjB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,kBAAkB,GACnB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,uBAAuB,EACvB,yBAAyB,EACzB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,sBAAsB,EACtB,KAAK,iBAAiB,EACtB,qBAAqB,EACrB,KAAK,qBAAqB,EAC1B,sBAAsB,EACtB,sBAAsB,EACtB,4BAA4B,EAC5B,wBAAwB,EACxB,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,wBAAwB,EACxB,KAAK,mBAAmB,EACxB,uBAAuB,GACxB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,4BAA4B,EAC5B,KAAK,mBAAmB,EACxB,2BAA2B,GAC5B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -12,7 +12,8 @@ export { createAgentRouter, createAgentTeam, } from "./router.js";
 export { MEMORY_TOOL_NAME, createRememberTool, RECALL_TOOL_NAME, createRecallTool, FORGET_TOOL_NAME, createForgetTool, PIN_TOOL_NAME, createPinTool, } from "./tools/memory.js";
 export { DELEGATE_TOOL_NAME, DELEGATED_BY_METADATA_KEY, ROOT_SESSION_ID_METADATA_KEY, DELEGATION_DEPTH_METADATA_KEY, DELEGATED_SESSION_ID_MARKER, DEFAULT_MAX_DELEGATION_DEPTH, isDelegatedSession, delegatingSessionIdOf, outstandingDelegationFor, withoutDelegation, createDelegateTool, } from "./tools/delegate.js";
 export { SCHEDULE_EVERY_TOOL_NAME, SCHEDULE_AT_TOOL_NAME, SCHEDULE_LIST_TOOL_NAME, SCHEDULE_CANCEL_TOOL_NAME, createScheduleTools, } from "./tools/schedule.js";
-export { MESSAGE_SEND_TOOL_NAME, createMessageSendTool, MESSAGE_READ_TOOL_NAME, MESSAGE_READ_MAX_LIMIT, MESSAGE_READ_TEXT_BUDGET, createMessageReadTool, directMessageReadRefusal, } from "./tools/message.js";
+export { MESSAGE_SEND_TOOL_NAME, createMessageSendTool, MESSAGE_READ_TOOL_NAME, MESSAGE_READ_MAX_LIMIT, MESSAGE_READ_BOOKMARK_BUDGET, MESSAGE_READ_TEXT_BUDGET, createMessageReadTool, directMessageReadRefusal, } from "./tools/message.js";
+export { CHANNEL_CREATE_TOOL_NAME, createChannelCreateTool, } from "./tools/channel.js";
 export { CREDENTIAL_REQUEST_TOOL_NAME, createCredentialRequestTool, } from "./tools/credentials.js";
 export { GATEWAY_ONLY_TOOL_NAMES } from "./tools/gateway-only.js";
 export { loadStratusSkill, STRATUS_SKILL_PATH } from "./builtin-skills.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,wEAAwE;AACxE,wEAAwE;AACxE,mEAAmE;AACnE,mDAAmD;AAEnD,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EACd,oBAAoB,EACpB,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAyB,WAAW,EAAE,MAAM,aAAa,CAAC;AAEjE,OAAO,EACL,iBAAiB,EAGjB,SAAS,EACT,UAAU,GACX,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,4BAA4B,EAC5B,8BAA8B,EAE9B,kBAAkB,EAGlB,qBAAqB,EAErB,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EAEL,oBAAoB,EACpB,gBAAgB,EAGhB,aAAa,EACb,mBAAmB,EACnB,aAAa,EACb,eAAe,EACf,wBAAwB,EACxB,2BAA2B,EAG3B,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAGL,iBAAiB,EACjB,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,aAAa,GAEd,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,4BAA4B,EAC5B,6BAA6B,EAC7B,2BAA2B,EAC3B,4BAA4B,EAC5B,kBAAkB,EAClB,qBAAqB,EACrB,wBAAwB,EACxB,iBAAiB,EAGjB,kBAAkB,GACnB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,uBAAuB,EACvB,yBAAyB,EACzB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,sBAAsB,EAEtB,qBAAqB,EAErB,sBAAsB,EACtB,sBAAsB,EACtB,wBAAwB,EAGxB,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,4BAA4B,EAE5B,2BAA2B,GAC5B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,wEAAwE;AACxE,wEAAwE;AACxE,mEAAmE;AACnE,mDAAmD;AAEnD,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EACd,oBAAoB,EACpB,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAyB,WAAW,EAAE,MAAM,aAAa,CAAC;AAEjE,OAAO,EACL,iBAAiB,EAGjB,SAAS,EACT,UAAU,GACX,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,4BAA4B,EAC5B,8BAA8B,EAE9B,kBAAkB,EAGlB,qBAAqB,EAErB,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EAEL,oBAAoB,EACpB,gBAAgB,EAGhB,aAAa,EACb,mBAAmB,EACnB,aAAa,EACb,eAAe,EACf,wBAAwB,EACxB,2BAA2B,EAG3B,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAGL,iBAAiB,EACjB,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,aAAa,GAEd,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,4BAA4B,EAC5B,6BAA6B,EAC7B,2BAA2B,EAC3B,4BAA4B,EAC5B,kBAAkB,EAClB,qBAAqB,EACrB,wBAAwB,EACxB,iBAAiB,EAGjB,kBAAkB,GACnB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,uBAAuB,EACvB,yBAAyB,EACzB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,sBAAsB,EAEtB,qBAAqB,EAErB,sBAAsB,EACtB,sBAAsB,EACtB,4BAA4B,EAC5B,wBAAwB,EAGxB,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,wBAAwB,EAExB,uBAAuB,GACxB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,4BAA4B,EAE5B,2BAA2B,GAC5B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/tools/channel.d.ts

@@ -0,0 +1,44 @@
+import type { Tool } from '@stratusagent/core';
+export declare const CHANNEL_CREATE_TOOL_NAME = "channel.create";
+/**
+ * Creates one conversation through the agent's own channel app. The
+ * gateway implements it over the channel contract's `createConversation`,
+ * structurally mirrored here the way `ConversationReader` mirrors
+ * `readConversation`; rejecting is how a channel says it will not.
+ */
+export type ConversationCreator = (input: {
+    agentId: string;
+    /** The channel kind, e.g. `slack`. */
+    channel: string;
+    name: string;
+    private?: boolean;
+    topic?: string;
+    purpose?: string;
+    /** Channel-native user ids, or agent ids the channel resolves to their app. */
+    invite?: string[];
+}) => Promise<{
+    conversation: string;
+    name: string;
+    invited: string[];
+    notInvited: Array<{
+        who: string;
+        reason: string;
+    }>;
+    notSet: Array<{
+        field: 'topic' | 'purpose';
+        reason: string;
+    }>;
+}>;
+/**
+ * Create a channel and invite people and other agents to it, so an agent
+ * can set up a client or project room without a person doing it by hand.
+ *
+ * `gated`, like `message.send`: a new channel and its invitations are seen
+ * by everyone invited, and a channel cannot be taken back by the agent.
+ * There is no destination to judge by before the channel exists, so a
+ * durable grant is a standing yes to creating channels. The channel's own
+ * app does the work with its own token, which never reaches the agent; the
+ * channel decides what its app may create.
+ */
+export declare const createChannelCreateTool: (create: ConversationCreator) => Tool;
+//# sourceMappingURL=channel.d.ts.map

package/dist/tools/channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../../src/tools/channel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAuB,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAEpE,eAAO,MAAM,wBAAwB,mBAAmB,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,KAAK,EAAE;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB,KAAK,OAAO,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnD,MAAM,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,OAAO,GAAG,SAAS,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC/D,CAAC,CAAC;AAaH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uBAAuB,GAAI,QAAQ,mBAAmB,KAAG,IAkEpE,CAAC"}

package/dist/tools/channel.js

@@ -0,0 +1,90 @@
+export const CHANNEL_CREATE_TOOL_NAME = 'channel.create';
+const optionalText = (input, key) => {
+    const value = input[key];
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (typeof value !== 'string') {
+        throw new Error(`${CHANNEL_CREATE_TOOL_NAME}: "${key}" must be a string when given.`);
+    }
+    return value.trim() || undefined;
+};
+/**
+ * Create a channel and invite people and other agents to it, so an agent
+ * can set up a client or project room without a person doing it by hand.
+ *
+ * `gated`, like `message.send`: a new channel and its invitations are seen
+ * by everyone invited, and a channel cannot be taken back by the agent.
+ * There is no destination to judge by before the channel exists, so a
+ * durable grant is a standing yes to creating channels. The channel's own
+ * app does the work with its own token, which never reaches the agent; the
+ * channel decides what its app may create.
+ */
+export const createChannelCreateTool = (create) => ({
+    name: CHANNEL_CREATE_TOOL_NAME,
+    description: 'Create a channel through your own app, optionally private, with a topic and purpose, and invite people and other agents to it. '
+        + 'invite takes the channel\'s user ids (for Slack, U…) and other agents\' ids on this host, which resolve to their apps. '
+        + 'Returns the new conversation id. The channel is kept even if some invites or the topic fail: '
+        + 'notInvited and notSet say what did not happen and why, so report those rather than retrying the create. '
+        + 'For Slack, names are lowercase letters, numbers, hyphens and underscores, at most 80 characters.',
+    risk: 'gated',
+    parameters: {
+        type: 'object',
+        properties: {
+            channel: { type: 'string', description: 'The channel kind to create it in, e.g. "slack".' },
+            name: { type: 'string', description: 'The new channel\'s name, without a leading #.' },
+            private: { type: 'boolean', description: 'Create a private channel. Public by default.' },
+            topic: { type: 'string', description: 'The channel\'s topic.' },
+            purpose: { type: 'string', description: 'The channel\'s purpose (its description).' },
+            invite: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Who to invite: user ids, or agent ids on this host. Your own app is already a member.',
+            },
+        },
+        required: ['channel', 'name'],
+    },
+    async execute(input, session) {
+        const channel = typeof input.channel === 'string' ? input.channel.trim() : '';
+        if (!channel) {
+            throw new Error(`${CHANNEL_CREATE_TOOL_NAME} requires "channel", the channel kind (e.g. "slack").`);
+        }
+        const name = typeof input.name === 'string' ? input.name.trim() : '';
+        if (!name) {
+            throw new Error(`${CHANNEL_CREATE_TOOL_NAME} requires a non-empty "name".`);
+        }
+        if (input.private !== undefined && typeof input.private !== 'boolean') {
+            throw new Error(`${CHANNEL_CREATE_TOOL_NAME}: "private" must be true or false.`);
+        }
+        const topic = optionalText(input, 'topic');
+        const purpose = optionalText(input, 'purpose');
+        let invite;
+        if (input.invite !== undefined && input.invite !== null) {
+            const raw = input.invite;
+            if (!Array.isArray(raw) || raw.some((entry) => typeof entry !== 'string' || entry.trim().length === 0)) {
+                throw new Error(`${CHANNEL_CREATE_TOOL_NAME}: "invite" must be a list of non-empty ids.`);
+            }
+            const unique = [...new Set(raw.map((entry) => entry.trim()))];
+            invite = unique.length > 0 ? unique : undefined;
+        }
+        const result = await create({
+            agentId: session.agent.id,
+            channel,
+            name,
+            ...(input.private === true ? { private: true } : {}),
+            ...(topic !== undefined ? { topic } : {}),
+            ...(purpose !== undefined ? { purpose } : {}),
+            ...(invite !== undefined ? { invite } : {}),
+        });
+        return {
+            created: true,
+            channel,
+            conversation: result.conversation,
+            name: result.name,
+            invited: [...result.invited],
+            notInvited: result.notInvited.map(({ who, reason }) => ({ who, reason })),
+            notSet: result.notSet.map(({ field, reason }) => ({ field, reason })),
+        };
+    },
+});
+//# sourceMappingURL=channel.js.map

package/dist/tools/channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.js","sourceRoot":"","sources":["../../src/tools/channel.ts"],"names":[],"mappings":"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"}

package/dist/tools/gateway-only.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gateway-only.d.ts","sourceRoot":"","sources":["../../src/tools/gateway-only.ts"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,uBAAuB,EAAE,SAAS,MAAM,EASpD,CAAC"}
+{"version":3,"file":"gateway-only.d.ts","sourceRoot":"","sources":["../../src/tools/gateway-only.ts"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,uBAAuB,EAAE,SAAS,MAAM,EAUpD,CAAC"}

package/dist/tools/gateway-only.js

@@ -1,3 +1,4 @@
+import { CHANNEL_CREATE_TOOL_NAME } from "./channel.js";
 import { CREDENTIAL_REQUEST_TOOL_NAME } from "./credentials.js";
 import { DELEGATE_TOOL_NAME } from "./delegate.js";
 import { MESSAGE_READ_TOOL_NAME, MESSAGE_SEND_TOOL_NAME } from "./message.js";
@@ -26,6 +27,7 @@ export const GATEWAY_ONLY_TOOL_NAMES = [
     SCHEDULE_CANCEL_TOOL_NAME,
     MESSAGE_SEND_TOOL_NAME,
     MESSAGE_READ_TOOL_NAME,
+    CHANNEL_CREATE_TOOL_NAME,
     DELEGATE_TOOL_NAME,
     CREDENTIAL_REQUEST_TOOL_NAME,
 ];

package/dist/tools/gateway-only.js.map

@@ -1 +1 @@
-{"version":3,"file":"gateway-only.js","sourceRoot":"","sources":["../../src/tools/gateway-only.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,4BAA4B,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAC9E,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,uBAAuB,EACvB,yBAAyB,GAC1B,MAAM,eAAe,CAAC;AAEvB;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAsB;IACxD,wBAAwB;IACxB,qBAAqB;IACrB,uBAAuB;IACvB,yBAAyB;IACzB,sBAAsB;IACtB,sBAAsB;IACtB,kBAAkB;IAClB,4BAA4B;CAC7B,CAAC"}
+{"version":3,"file":"gateway-only.js","sourceRoot":"","sources":["../../src/tools/gateway-only.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,4BAA4B,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAC9E,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,uBAAuB,EACvB,yBAAyB,GAC1B,MAAM,eAAe,CAAC;AAEvB;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAsB;IACxD,wBAAwB;IACxB,qBAAqB;IACrB,uBAAuB;IACvB,yBAAyB;IACzB,sBAAsB;IACtB,sBAAsB;IACtB,wBAAwB;IACxB,kBAAkB;IAClB,4BAA4B;CAC7B,CAAC"}

package/dist/tools/message.d.ts

@@ -60,6 +60,14 @@ export declare const MESSAGE_READ_MAX_LIMIT = 200;
  * agent pages on with `before`/`after`.
  */
 export declare const MESSAGE_READ_TEXT_BUDGET = 40000;
+/**
+ * The share of `MESSAGE_READ_TEXT_BUDGET` a channel's bookmarks may take,
+ * counted first. It holds Slack's limit of 100 at a typical length; what
+ * it exists to stop is the people in a channel filling the agent's context
+ * with bookmarks. The ones that do not fit are counted, not paged: Slack
+ * lists them all in one call.
+ */
+export declare const MESSAGE_READ_BOOKMARK_BUDGET = 16000;
 /**
  * Reads one conversation, or one thread in it, through the agent's own
  * channel app. The gateway implements it over the channel contract's
@@ -68,6 +76,8 @@ export declare const MESSAGE_READ_TEXT_BUDGET = 40000;
  */
 export type ConversationReader = (input: {
     agentId: string;
+    /** The session reading: a direct message is readable only from its own. */
+    sessionId: string;
     source: ScheduleDestination;
     thread?: string;
     after?: string;
@@ -85,6 +95,12 @@ export type ConversationReader = (input: {
         files?: string[];
     }>;
     more: boolean;
+    bookmarks?: Array<{
+        title: string;
+        link: string;
+    }>;
+    bookmarksUnavailable?: string;
+    bookmarksOmitted?: number;
 }>;
 /**
  * Read a conversation's recent messages, or one thread — so an agent can

package/dist/tools/message.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"message.d.ts","sourceRoot":"","sources":["../../src/tools/message.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsC,KAAK,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAClH,OAAO,EACL,KAAK,mBAAmB,EAIzB,MAAM,iBAAiB,CAAC;AAEzB,eAAO,MAAM,sBAAsB,iBAAiB,CAAC;AAErD;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,mBAAmB,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,OAAO,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,UAAU,CAAA;KAAE,CAAC;CACpD,KAAK,OAAO,CAAC;IAAE,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAAC;AAEtC;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,mBAAmB,KAAK,MAAM,GAAG,SAAS,CAAC;AAE/G;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,GAChC,MAAM,iBAAiB,EACvB,UAAS;IAAE,aAAa,CAAC,EAAE,qBAAqB,CAAA;CAAO,KACtD,IAmED,CAAC;AAEH,eAAO,MAAM,sBAAsB,iBAAiB,CAAC;AAErD,yDAAyD;AACzD,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAG/C;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,mBAAmB,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf,KAAK,OAAO,CAAC;IACZ,QAAQ,EAAE,KAAK,CAAC;QACd,EAAE,EAAE,MAAM,CAAC;QACX,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,IAAI,EAAE,MAAM,CAAC;QACb,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;KAClB,CAAC,CAAC;IACH,IAAI,EAAE,OAAO,CAAC;CACf,CAAC,CAAC;AAaH;;;;;;;;;;;;;;GAcG;AACH;;;;;GAKG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,KAAK,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAA;CAAE,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;AAElJ,0EAA0E;AAC1E,eAAO,MAAM,wBAAwB,GAAI,aAAa,MAAM,KAAG,MAGQ,CAAC;AAExE,eAAO,MAAM,qBAAqB,GAChC,MAAM,kBAAkB,EACxB,UAAS;IAAE,UAAU,CAAC,EAAE,uBAAuB,CAAA;CAAO,KACrD,IAyFD,CAAC"}
+{"version":3,"file":"message.d.ts","sourceRoot":"","sources":["../../src/tools/message.ts"],"names":[],"mappings":"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"}

package/dist/tools/message.js

@@ -93,6 +93,14 @@ const MESSAGE_READ_DEFAULT_LIMIT = 50;
  * agent pages on with `before`/`after`.
  */
 export const MESSAGE_READ_TEXT_BUDGET = 40_000;
+/**
+ * The share of `MESSAGE_READ_TEXT_BUDGET` a channel's bookmarks may take,
+ * counted first. It holds Slack's limit of 100 at a typical length; what
+ * it exists to stop is the people in a channel filling the agent's context
+ * with bookmarks. The ones that do not fit are counted, not paged: Slack
+ * lists them all in one call.
+ */
+export const MESSAGE_READ_BOOKMARK_BUDGET = 16_000;
 const TRUNCATED_MARK = ' [... the rest of this message is not shown]';
 const optionalId = (input, key, tool = MESSAGE_READ_TOOL_NAME) => {
     const value = input[key];
@@ -105,18 +113,20 @@ const optionalId = (input, key, tool = MESSAGE_READ_TOOL_NAME) => {
     return value.trim();
 };
 /** The refusal a direct-message read gets, before any approval prompt. */
-export const directMessageReadRefusal = (destination) => `message.read cannot read ${destination}: it is a direct message, and direct messages are never read from outside them. `
+export const directMessageReadRefusal = (destination) => `message.read cannot read ${destination}: it is a direct message this conversation is not in, and a direct message is read only from inside it. `
     + 'This is not a permission, so approval cannot unlock it; do not ask for one or try again. '
     + 'Read a channel instead, or ask the person to paste what you need.';
 export const createMessageReadTool = (read, options = {}) => ({
     name: MESSAGE_READ_TOOL_NAME,
     description: 'Read recent messages in a channel your app is a member of, or one thread in it. '
-        + 'Direct messages and group DMs cannot be read with this, and approval does not change that. '
+        + 'Direct messages and group DMs cannot be read with this, except the one this conversation is in, and approval does not change that. '
         + 'Without thread: the top level, newest first. With thread: that thread\'s root and replies, oldest first. '
         + 'For Slack, ids are channel ids and message ts values; a permalink '
         + '…/archives/C0123456789/p1791332967606559 is channel C0123456789 and message 1791332967.606559, '
         + 'and a thread_ts in the link is the thread to read. '
-        + 'When more is true, page on with before (top level) or after (thread) set to the last id returned.',
+        + 'When more is true, page on with before (top level) or after (thread) set to the last id returned. '
+        + 'A top-level read without before or after also returns the channel\'s bookmarks, when it has any; '
+        + 'if bookmarksOmitted is set, say that many were left out rather than guess them.',
     risk: 'gated',
     outputTrust: 'external',
     parameters: {
@@ -158,14 +168,35 @@ export const createMessageReadTool = (read, options = {}) => ({
             : MESSAGE_READ_DEFAULT_LIMIT;
         const result = await read({
             agentId: session.agent.id,
+            sessionId: session.id,
             source,
             limit,
             ...(thread !== undefined ? { thread } : {}),
             ...(after !== undefined ? { after } : {}),
             ...(before !== undefined ? { before } : {}),
         });
-        const messages = [];
+        // Bookmarks first, from their own share, in the channel's order.
+        const bookmarks = [];
         let used = 0;
+        for (const bookmark of result.bookmarks ?? []) {
+            // Counted as the list is serialized: each entry with its separator,
+            // plus the closing bracket.
+            const size = JSON.stringify(bookmark).length + 1;
+            if (used + size + 1 > MESSAGE_READ_BOOKMARK_BUDGET) {
+                break;
+            }
+            bookmarks.push({ title: bookmark.title, link: bookmark.link });
+            used += size;
+        }
+        if (bookmarks.length > 0) {
+            used += 1;
+        }
+        // Added to what the adapter itself already left out, if it said.
+        const upstreamOmitted = typeof result.bookmarksOmitted === 'number' && Number.isInteger(result.bookmarksOmitted) && result.bookmarksOmitted > 0
+            ? result.bookmarksOmitted
+            : 0;
+        const bookmarksOmitted = upstreamOmitted + (result.bookmarks?.length ?? 0) - bookmarks.length;
+        const messages = [];
         let more = result.more;
         for (const message of result.messages) {
             const size = JSON.stringify(message).length;
@@ -177,13 +208,36 @@ export const createMessageReadTool = (read, options = {}) => ({
             // One message bigger than the whole budget is cut rather than
             // dropped, or the read could never get past it. Its file list goes
             // too, said by count, since a list can be as long as any text.
+            // One that would fit on its own, crowded out only by the bookmarks
+            // ahead of it, loses about what they took rather than half.
             if (messages.length === 0) {
                 const { files, ...rest } = message;
-                const cut = {
+                const cutTo = (keep) => ({
                     ...rest,
-                    text: message.text.slice(0, MESSAGE_READ_TEXT_BUDGET / 2) + TRUNCATED_MARK,
+                    text: message.text.slice(0, Math.max(0, keep)) + TRUNCATED_MARK,
                     ...(files && files.length > 0 ? { files: [`${files.length} files, not listed`] } : {}),
-                };
+                });
+                let cut = cutTo(MESSAGE_READ_TEXT_BUDGET / 2);
+                if (used > 0 && size <= MESSAGE_READ_TEXT_BUDGET) {
+                    // The longest cut that fits, measured as serialized, since
+                    // escapes make the text longer and may sit anywhere in it.
+                    const room = MESSAGE_READ_TEXT_BUDGET - used;
+                    const fits = (keep) => JSON.stringify(cutTo(keep)).length <= room;
+                    if (fits(0)) {
+                        let low = 0;
+                        let high = message.text.length;
+                        while (low < high) {
+                            const middle = Math.ceil((low + high) / 2);
+                            if (fits(middle)) {
+                                low = middle;
+                            }
+                            else {
+                                high = middle - 1;
+                            }
+                        }
+                        cut = cutTo(low);
+                    }
+                }
                 messages.push(cut);
             }
             more = true;
@@ -194,6 +248,9 @@ export const createMessageReadTool = (read, options = {}) => ({
             ...(thread !== undefined ? { thread } : {}),
             count: messages.length,
             more,
+            ...(bookmarks.length > 0 ? { bookmarks } : {}),
+            ...(bookmarksOmitted > 0 ? { bookmarksOmitted } : {}),
+            ...(result.bookmarksUnavailable !== undefined ? { bookmarksUnavailable: result.bookmarksUnavailable } : {}),
             messages,
         };
     },

package/dist/tools/message.js.map

@@ -1 +1 @@
-{"version":3,"file":"message.js","sourceRoot":"","sources":["../../src/tools/message.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"message.js","sourceRoot":"","sources":["../../src/tools/message.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stratusagent/agents",
-  "version": "0.13.5",
+  "version": "0.13.7",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -18,7 +18,7 @@
     "node": ">=22.13 <23 || >=23.4"
   },
   "dependencies": {
-    "@stratusagent/core": "0.13.5"
+    "@stratusagent/core": "0.13.7"
   },
   "devDependencies": {
     "@types/node": "^24.6.0",

package/skills/stratus/SKILL.md

@@ -24,6 +24,7 @@ Everything is under `~/.stratus/` on the daemon's machine:
 | --- | --- |
 | `config.json` | The global config, and the trusted one (see "Config"). `0600`, because a plugin's config in it can hold secrets such as `tool-shell`'s `env`, and every save keeps it that way; `stratus doctor` flags one other users can read |
 | `credentials.json` | Provider sign-ins (shared, and any agent's own under `agentSignIns.<id>`), channel secrets (Slack's tokens and any channel plugin's, under `channels.<kind>.<agentId>`), and named credentials. `0600`, and kept that way by Stratus, which is why it is edited with `stratus credential set` and `stratus channel set` rather than by hand |
+| `credential-audit.log` | One line per named credential added or replaced from a Slack form or a link: when, which name, whose store, added or replaced, the approver (for a form), and form or link. Names only, never a value. `0600` |
 | `agents/<file>.md` | A soul: one agent's identity and allowlists. The file name is not the id; the id is the soul's `id:`, or derived from its `name:`. Use the id your instructions give |
 | `agents/<id>/` | That agent's state: `sessions.db`, `memory.jsonl`, `whitelist.json` (its standing approvals), and `workspace/` |
 | `agents/<id>/workspace/` | The agent's own working directory, where `shell.run` starts by default |
@@ -66,22 +67,27 @@ When a setting "isn't taking", these say why:
 
 ## Credentials and API keys
 
-This is the question you will be asked most. A secret reaches Stratus in one of four ways, and which one depends on what uses it:
+This is the question you will be asked most. A secret reaches Stratus in one of these ways, and which one depends on what uses it:
 
 - **Provider sign-ins** (the model's own key or subscription): `stratus setup` → Providers, or the dashboard. There is no `stratus login`.
 - **One agent on its own Claude subscription**: `stratus signin set anthropic --agent <id>` at the machine, with a token from `claude setup-token` typed at the hidden prompt or piped on stdin. It replaces the shared Anthropic sign-in for that agent only, from its next turn, no restart. `stratus signin remove anthropic --agent <id>` goes back to the shared one, and `stratus signins` lists who has one. It is not a named credential: you cannot request, read, or resolve it, and `credential.request` is the wrong tool for it. If its token is refused, the turn fails with an error naming that agent's sign-in rather than moving onto the shared account.
 - **Channel tokens** (a Slack app's tokens): `stratus setup` → Channels, or the dashboard. No agent can read them, yours included.
-- **Named credentials**, such as `search.apiKey`, are for tools whose plugin declares that name. A web search backend is the common one: its key is always `search.apiKey`, whatever the vendor. These are the only secrets you can ask for yourself.
-- **A shell command's or an MCP server's token** is not a named credential: `shell.run` and MCP servers never read the credential store. Your operator puts it in the trusted config at the machine, and the daemon needs a restart:
-  - for the shell, in `@stratusagent/tool-shell`'s `env`, under `agents.<id>` to keep it to one agent (whose commands can then read it). An agent's `env` is added to the shared one rather than replacing it, its own names win, and a name set to `null` there is withheld from that agent;
-  - for an MCP server, in `servers.<name>.headers` (HTTP) or `servers.<name>.env` (stdio), which every agent granted `mcp.<name>.*` uses. Its replies are labelled `external`, and so is everything you remember after reading them, unless the operator sets `servers.<name>.outputTrust` to `agent` (or `unknown`) for a server they run; never `user`.
+- **Named credentials**, such as `search.apiKey` or `github.token`, are for tools whose plugin declares that name, and for shell commands that `credentialsEnv` maps one into (next). A web search backend is the common one: its key is always `search.apiKey`, whatever the vendor. These are the only secrets you can ask for yourself.
+- **A shell command's token** reaches `shell.run` as an environment variable. Your operator sets that up in the trusted config at the machine, and a change there needs a daemon restart:
+  - from the credential store, with `@stratusagent/tool-shell`'s `credentialsEnv`: `{ "GH_TOKEN": "github.token" }` gives each of your commands your stored `github.token` in `GH_TOKEN`, so a CLI that reads its token from a variable just works. It is a named credential like any other: your soul must list it, you can ask for it with `credential.request`, and a replaced value reaches the next command with no restart. Fleet-wide, or under `agents.<id>` for one agent;
+  - or as a value written into tool-shell's `env`, under `agents.<id>` to keep it to one agent. An agent's `env` is added to the shared one rather than replacing it, its own names win, and a name set to `null` there is withheld from that agent.
 
-  `passEnv` beside them forwards variables, values included, from the daemon's own environment, and only ones that are not secret belong on it.
+  Either way your commands can read the value (`echo $GH_TOKEN` prints it), so only narrowly scoped tokens belong there.
+- **An MCP server's token** is not a named credential: MCP servers never read the credential store. Your operator puts it in `servers.<name>.headers` (HTTP) or `servers.<name>.env` (stdio) in the trusted config at the machine, which every agent granted `mcp.<name>.*` uses, and the daemon needs a restart. Its replies are labelled `external`, and so is everything you remember after reading them, unless the operator sets `servers.<name>.outputTrust` to `agent` (or `unknown`) for a server they run; never `user`.
 
-For a named credential to reach you, three things must all be true. It is **stored**, your soul's `credentials:` **lists its name**, and a tool you have **declares it**. Storing grants nothing by itself. You never see the value, and there is no file or variable for you to look in. Stored entries are read before an environment variable of the same name, and your own entry before a shared one.
+  `passEnv` beside tool-shell's or a server's `env` forwards variables, values included, from the daemon's own environment, and only ones that are not secret belong on it.
+
+For a named credential to reach you, three things must all be true. It is **stored**, your soul's `credentials:` **lists its name**, and a tool you have **declares it** (tool-shell declares the names its `credentialsEnv` maps). Storing grants nothing by itself. Tools use the value on your behalf, and there is no file for you to look in. The one place a value shows up is a `shell.run` command's environment, in the variable `credentialsEnv` maps it to. Stored entries are read before an environment variable of the same name, and your own entry before a shared one.
 
 When you need a named credential you do not hold, first make sure a tool you have uses that name. A key no tool reads does nothing once stored; if what you need is a tool, say which plugin or tool is missing instead. Then:
 
+**In Slack, the form comes first.** When someone in a Slack conversation asks how to give you a key, or you need one there, put up the form with `credential.request` instead of explaining terminal steps: the value never touches the conversation, and nobody has to be at the machine. Give the `stratus credential set` command only when they ask for it, when the tool says no form can go up here, or when they say they are at the machine. For example, asked in a Slack thread "how do I give you the GitHub token?", call `credential.request` with `name: "github.token"` and a reason, then reply: "I put a secure form in this thread. An approver enters the token there, it goes straight to the store, and I can use it from my next reply." Not a paragraph of `read -rs KEY` steps.
+
 1. **Ask with `credential.request`**. Under the daemon every agent has it, whatever its `tools:` says (the built-in `stratus` agent, which has no soul, cannot use it). Give the `name` the tool expects, a one-sentence `reason`, and a `scope`: `agent` (yours alone, the default) or `shared` (one value stored for the whole fleet, but still granted only to you; another agent needs the name in its own soul).
    - **A form**, in Slack, goes up in this conversation when one of `approvals.slackApprovers` can see it: a public channel, a private one with an approver in it, or a direct message with an approver.
    - **A link** comes back otherwise, or when you pass `via: "link"`, but only if your soul's `tools:` lists `credential.request` (or you have no `tools:` key); without that, it is a form or nothing. It needs the control API, and without `api.publicUrl` it opens only on the daemon's machine. Anyone who has the link can set the key, once, within 30 minutes, with no approver involved, and opening it spends nothing. So give it only to your operator. In a shared channel, or a direct message with anyone else, do not post it: ask your operator to message you directly, and ask again there. Pass `via: "form"` to get a form or nothing.
@@ -94,7 +100,7 @@ When you need a named credential you do not hold, first make sure a tool you hav
 
    (leave out `--agent` for a shared one), and to add `<name>` to `credentials:` in your soul.
 
-Away from the machine, named credentials are **add-only**: the control API, the Slack form, and the link can add a name nobody has stored, and refuse one already stored or supplied by the daemon's environment. Replacing or removing one is `stratus credential set` or `stratus credential remove` at the machine, because a replaced shared key moves every agent using it onto another account. `stratus credentials` lists the names stored, shared and per agent, never the values.
+Away from the machine, the control API and a link only **add**: they store a name nobody has stored, and refuse one already stored or supplied by the daemon's environment. The Slack form adds too, and it is the one way to **replace** a key from chat. When one you hold is expiring or was revoked, call `credential.request` with `replace: true`. That is always a form an approver answers in this conversation, never a link. It is refused before anyone is asked when you don't hold the key, when it comes from the daemon's environment, or when your `scope` doesn't match where it is stored: a shared key needs `scope: "shared"`, because replacing it changes the key for every agent granted it. The new value is used from the next tool call or command. At the machine, `stratus credential set` replaces as well, and `stratus credential remove` is the only way to remove one. Each add or replace from a form or a link appends a line to `~/.stratus/credential-audit.log`, names only. `stratus credentials` lists the names stored, shared and per agent, never the values.
 
 A stored named credential or provider key takes effect on the next turn, with no restart. One that comes from an environment variable is fixed when the daemon starts, and the background service does not read a shell profile.
 
@@ -106,7 +112,7 @@ When a stored key "isn't found", check in this order:
 
 ## Tools, plugins, and approvals
 
-- **Built in everywhere:** `memory.*` (remember, recall, forget, pin) and `skill.read`, which every agent has because this skill counts. **Only under the daemon:** `schedule.*`, `message.send`, `message.read`, `agent.delegate`, and `credential.request`, so `stratus run` and `stratus chat` cannot call them.
+- **Built in everywhere:** `memory.*` (remember, recall, forget, pin) and `skill.read`, which every agent has because this skill counts. **Only under the daemon:** `schedule.*`, `message.send`, `message.read`, `channel.create`, `agent.delegate`, and `credential.request`, so `stratus run` and `stratus chat` cannot call them.
 - **Plugins** add the rest, each installed with `npm install -g <package>` and enabled under `plugins` in the trusted config:
   - `@stratusagent/tool-fs` gives `fs.*`, inside configured roots only, so with no roots there is no filesystem. Whatever the roots, `fs.*` never reaches `~/.stratus` outside the agents' workspaces (credentials, config, logs, sessions, memories, souls, skills, grants), so a refusal there is by design, not a roots problem. Roots go in `"@stratusagent/tool-fs": { "enabled": true, "roots": ["~/notes"] }`, or under `"agents": { "<id>": { "roots": [...] } }` for one agent.
   - `@stratusagent/tool-shell` gives `shell.run`.
@@ -117,7 +123,7 @@ When a stored key "isn't found", check in this order:
 - Enabled is not granted: your soul's `tools:` must also cover a plugin's tools. `stratus plugins` walks the whole chain for each tool (installed, enabled, granted to which agents, and what approvals do with a call), so it answers "why can't you use X" in one command.
 - **Risk.** Every tool is `safe`, `gated`, or `dangerous`. The daemon runs `safe` tools unattended, among them `memory.*`, `skill.read`, `credential.request`, `agent.delegate`, `schedule.list`, `schedule.cancel`, and `fs.read`, `fs.list`, and `fs.search`. Gated tools include:
   - `web.fetch`, `fs.write`, `fs.move`, `shell.run`, `browser.*`, and `mcp.*`;
-  - `schedule.every`, `schedule.at`, `message.send`, and `message.read` (which reads a channel your Slack app is in, never a DM, and labels what it returns `external`; a DM read is refused before any approval prompt, since approving can't make it run);
+  - `schedule.every`, `schedule.at`, `message.send`, `message.read` (which reads a channel your Slack app is in, or the DM you're talking in, never any other DM, and labels what it returns `external`; a top-level read also returns the channel's bookmarks, which need the `bookmarks:read` scope; a DM read is refused before any approval prompt, since approving can't make it run), and `channel.create` (which makes a channel with your own app and invites people and agents; on Slack it needs the `channels:manage` or `groups:write` scope, which apps don't have by default, and a failed invite or topic is reported while the channel stays, so don't retry the create);
   - every third-party tool, `web.search` included.
   - Under the default `approvals.posture: "open"` a gated call runs without asking; what needs approval is a dangerous call (and, under `externalContent: "gate"`, a gated one after external content). Under `"guarded"` every uncovered gated call does. What happens to a call that needs approval depends on the approvals mode. Under `headless` (the default) it is refused. Under `remote` the people in `approvals.slackApprovers` are asked in Slack (or through the control API's `/approvals`) with **Allow once**, **Always allow**, and **Deny**. Under `remote` with nobody to ask, it is refused too.
   - Either way, what was already approved still runs unattended. For `shell.run` that is a command scope, a command granted by name, plus a short built-in safe list (`cd`, `pwd`, `echo`, `true`, `false`, `whoami`, and `uname`; no `git` command, not even `git status`, since git runs programs a repository names), plus `grep`, `head`, `tail`, `wc`, `sort`, and `uniq` as filters that are never handed a path, and `cat`, `head`, `tail`, and `ls` of files inside your workspace. **Always allow** on a command like `grep` grants it by name: any arguments, as long as the line runs in your workspace and every path it names resolves inside it. A command with subcommands (`git push`, `gh pr`) keeps a command-plus-subcommand scope, and shells, interpreters, wrappers like `xargs` or `sudo`, and system commands are never granted by name. A line joined by `&&`, `||`, `;`, or `|` runs unattended when every command in it would on its own, and output may be redirected into your workspace or `/dev/null`; a background `&`, a newline, `$( )`, a heredoc, or a redirection elsewhere still means asking. For `browser.act` and `web.fetch` it is an approved site (a `web.fetch` redirect to another site is reported as `redirectedTo`, not followed), and for other gated tools a standing grant.
@@ -166,7 +172,7 @@ When a stored key "isn't found", check in this order:
 - In a container or under a system unit, `stratus serve --log-format json` also writes the log's records to stdout, for `docker logs`, journald, or a log shipper. `stratus health` is the probe.
 - **`stratus logs`** (`-f` to follow, `--agent`, `--session`) reads the structured log. It records that tools ran and sessions finished, never prompts or replies. One exception: a failed session keeps the provider's error text, so skim a log before sharing it.
   - A daemon that fails *before* it starts serving writes nothing there. Its error is in `~/.stratus/logs/stratusd.err.log` on macOS, in `journalctl --user-unit=stratusd.service` on Linux, or on the terminal that ran `stratus serve`.
-- **The control API** is a separate install, `@stratusagent/control-api`, serving `/api/v1` on `127.0.0.1:4123`. The web dashboard is another, `@stratusagent/dashboard`, opened with `stratus dashboard`, which starts a daemon if none is running.
+- **The control API** is a separate install, `@stratusagent/control-api`, serving `/api/v1` on `127.0.0.1:4123`. The web dashboard is another, `@stratusagent/dashboard`, opened with `stratus dashboard`, which offers to install both when they are missing and starts a daemon if none is running.
   - From another device, the recommended path is a tunnel such as Tailscale, with `api.publicUrl` set to that address so credential links open there.
 
 ## When a reply stops or changes model
@@ -188,6 +194,7 @@ When a stored key "isn't found", check in this order:
 | `stratus restart` | Announced drain-and-restart of the running daemon |
 | `stratus logs` | Read the daemon's log |
 | `stratus health` | Whether the running daemon is serving: exit 0 if so, for a container healthcheck or a probe |
+| `stratus sessions` (also `stratus session list`) | The running daemon's sessions, newest first: status, agent, last update, id. `--agent <id>`, `--status <status>` (`running`, `pending_approval`, `failed`, `completed`, `idle`), `--limit <n>` (default 20), `--format json` |
 | `stratus doctor` | What a run would use, and why |
 | `stratus update` | Update Stratus and its companion packages (`--check` to look first) |
 | `stratus dashboard` | Open the web dashboard with a one-time sign-in link |
@@ -221,10 +228,10 @@ Only at the machine can someone:
 
 - enable or configure a plugin (its `env` and `headers` included), or choose an executor or memory store;
 - install or update packages;
-- replace or remove a named credential;
+- remove a named credential, or replace one without an approver's form;
 - raise a memory's trust (`stratus memory reassert`).
 
-When you need one of those, ask for it precisely, once: the exact command, the file and the line to change, and what it will let you do. For example: "Run `stratus credential set search.apiKey --agent kai` with the key on stdin, and add `search.apiKey` under `credentials:` in my soul. Once a search plugin is enabled, `web.search` is in my `tools:`, and approvals let it run, I can search." Not a list of possibilities, and not a guess presented as a step.
+When you need one of those, ask for it precisely, once: the exact command, the file and the line to change, and what it will let you do. For example: "In `~/.stratus/config.json`, add `"credentialsEnv": { "GH_TOKEN": "github.token" }` under `agents.kai` in the `@stratusagent/tool-shell` block, then run `stratus restart`. After that, `gh` in my shell uses the `github.token` I already hold." Not a list of possibilities, and not a guess presented as a step.
 
 ## Going further