Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
ts 96 lines 4.11 KB
Raw
1 import { Effect, Option } from 'effect';
2 import { uuidv5 } from 'uniku/uuid/v5';
3 import { HOST_CONFIG, telemetryDisabled, type AgentSessionEnvironment } from 'src/config';
4 import { AGENT_HOSTS, type AgentHost } from './agent-host';
5
6 /** A chat as its agent host identifies it. The host's ID stays on this device. */
7 export type HostSession = {
8 readonly host: AgentHost;
9 readonly hostSessionId: string;
10 };
11
12 /** The agent session a command is part of: the host, and the ID derived for its chat. */
13 export type AgentSession = {
14 readonly host: AgentHost;
15 readonly id: string;
16 };
17
18 /** The pair a plugin hook exported, when it names a known host and carries a session ID. */
19 const exportedSession = (env: AgentSessionEnvironment): Option.Option<HostSession> =>
20 Option.all({
21 host: Option.fromUndefinedOr(AGENT_HOSTS.find(host => host === env.hookHost)),
22 hostSessionId: Option.fromUndefinedOr(env.hookSessionId),
23 });
24
25 /** Each host's own session ID. Codex versions without `CODEX_SESSION_ID` set only a thread ID. */
26 const ownSessionIds = (env: AgentSessionEnvironment): Record<AgentHost, string | undefined> => ({
27 claude: env.claudeCodeSessionId,
28 codex: env.codexSessionId ?? env.codexThreadId,
29 });
30
31 /** The one host whose own variable is set. Two hosts cannot be ordered, so they give none. */
32 const soleOwnSession = (env: AgentSessionEnvironment): Option.Option<HostSession> => {
33 const ids = ownSessionIds(env);
34 const [session, ...others] = AGENT_HOSTS.flatMap((host): ReadonlyArray<HostSession> => {
35 const hostSessionId = ids[host];
36 return hostSessionId === undefined ? [] : [{ host, hostSessionId }];
37 });
38 return session !== undefined && others.length === 0 ? Option.some(session) : Option.none();
39 };
40
41 /**
42 * Picks the chat this process runs in from the agent session variables.
43 *
44 * The pair a plugin hook exported wins, because child processes inherit it: a host started
45 * inside another host's chat still reports the parent chat. Without a usable export, the one
46 * host whose own variable is set is used. Blank variables already read as `undefined` (see
47 * `HOST_CONFIG`).
48 *
49 * This reads no telemetry switch. Callers go through `resolveAgentSession`.
50 */
51 export const selectHostSession = (env: AgentSessionEnvironment): Option.Option<HostSession> =>
52 Option.orElse(exportedSession(env), () => soleOwnSession(env));
53
54 /**
55 * The namespace every agent session ID is derived under. A UUID v5 needs one, and this one is
56 * itself the UUID v5 of the name below under the RFC 9562 URL namespace, so nothing here is
57 * an arbitrary number. The name labels the scheme and does not have to resolve. `uuidv5.NIL`
58 * or `uuidv5.MAX` would be accepted too, but they belong to no one: any other system hashing
59 * the same `<host>:<id>` name under them would produce our IDs.
60 *
61 * Frozen. Another name changes every derived ID and splits each chat in two. Any system that
62 * holds a host and its session ID derives the same ID from this value.
63 */
64 export const AGENT_SESSION_NAMESPACE = uuidv5(
65 'https://composio.dev/ns/agent-session/v1',
66 uuidv5.URL
67 );
68
69 const deriveInAgentSessionNamespace = uuidv5.namespace(AGENT_SESSION_NAMESPACE);
70
71 /**
72 * The UUID v5 of `<host>:<host session ID>`. Surrounding whitespace was dropped when the
73 * variables were read (see `HOST_CONFIG`); nothing else is changed, letter case included.
74 */
75 export const deriveAgentSessionId = ({ host, hostSessionId }: HostSession): string =>
76 deriveInAgentSessionNamespace(`${host}:${hostSessionId}`);
77
78 /**
79 * The agent session this command is part of, or none outside a known agent host.
80 *
81 * Telemetry is checked here, before any session variable is read, so every consumer resolves
82 * none while an opt-out, a test run, or CI disables it. The result never carries the host's
83 * own session ID.
84 */
85 export const resolveAgentSession: Effect.Effect<Option.Option<AgentSession>> = Effect.gen(
86 function* () {
87 if (yield* telemetryDisabled) {
88 return Option.none();
89 }
90 const hostSession = selectHostSession(yield* Effect.orDie(HOST_CONFIG.AGENT_SESSION));
91 return Option.map(hostSession, session => ({
92 host: session.host,
93 id: deriveAgentSessionId(session),
94 }));
95 }
96 );