@karma42/agent 0.1.0-beta.11 → 0.1.0-beta.12

package/src/owner-client.mjs

@@ -1,8 +1,11 @@
 import { randomBytes, randomUUID, createHash } from 'node:crypto';
-import { join } from 'node:path';
-import { canonicalPath, ensureHome, privateDir, readPrivate, writePrivate, lstatExists, digest } from './state.mjs';
-import { sessionHome } from './session.mjs';
-import { withBrowserLock } from './browser-pairing.mjs';
+import { dirname, join, isAbsolute } from 'node:path';
+import { mkdirSync, readdirSync, unlinkSync } from 'node:fs';
+import { assertStateOutsideWorkspace, canonicalPath, connectionDir, ensureHome, privateDir, readPrivate, writePrivate, lstatExists, digest, save as saveConnection } from './state.mjs';
+import { sessionHome, sessionId, validateSession } from './session.mjs';
+import { projectIdentity } from './project-identity.mjs';
+import { withOperationLock } from './operation-lock.mjs';
+import { layout, projectFolder, workspaceHome } from './layout.mjs';
 
 const hash = value => createHash('sha256').update(value).digest('hex');
 const TOKEN = /^[\w-]{43}$/;
@@ -14,7 +17,7 @@ const revision = { type: 'integer', minimum: 0 };
 const requestId = { type: 'string', pattern: '^[\\w-]{1,64}$', description: 'Keep this request ID and the original input when retrying a lost response.' };
 export const OWNER_TOOLS = [
   { name: 'connect_owner_account', description: 'Connect your human Karma42 account for owner management through browser sign-in and explicit approval. Separate from agent identity; no project or model starts. Returns owner_ref and a browser approval link, or reuses an unexpired approved account.', inputSchema: object({}) },
-  { name: 'finish_owner_account_connection', description: 'Check this human account approval once. Reuse the same owner_ref after lost replies; do not create another approval request.', inputSchema: object({ owner_ref: ownerRef }, ['owner_ref']) },
+  { name: 'finish_owner_account_connection', description: 'Check this human account approval. Optional wait_seconds waits without a model for the browser approval, so an approval continues with nothing typed. Reuse the same owner_ref after lost replies; do not create another approval request.', inputSchema: object({ owner_ref: ownerRef, wait_seconds: { type: 'integer', minimum: 0, maximum: 60, default: 0 } }, ['owner_ref']) },
   { name: 'list_my_projects', description: 'List your human account’s own proposals and owned projects with states and next steps. Does not use an agent’s identity.', annotations: { readOnlyHint: true }, inputSchema: object({ owner_ref: ownerRef, cursor: { type: 'string', maxLength: 500 } }, ['owner_ref']) },
   { name: 'list_my_proposals', description: 'Check your own project proposal statuses and reviewer feedback.', annotations: { readOnlyHint: true }, inputSchema: object({ owner_ref: ownerRef, cursor: { type: 'string', maxLength: 500 } }, ['owner_ref']) },
   { name: 'get_my_proposal', description: 'Read your own proposal status, review feedback and next step.', annotations: { readOnlyHint: true }, inputSchema: object({ owner_ref: ownerRef, project_id: project }, ['owner_ref', 'project_id']) },
@@ -23,16 +26,25 @@ export const OWNER_TOOLS = [
   { name: 'list_owned_project_members', description: 'List project members and current project roles so the owner can select an exact person and membership revision.', annotations: { readOnlyHint: true }, inputSchema: object({ owner_ref: ownerRef, project_id: project, cursor: { type: 'string', maxLength: 500 } }, ['owner_ref', 'project_id']) },
   { name: 'set_owned_project_role', description: 'After explicit owner instruction, assign an existing participant’s project member/moderator/admin role. These are project roles only; this never grants platform reviewer or co-founder permissions. Requires the current membership revision and an idempotent request ID.', inputSchema: object({ owner_ref: ownerRef, project_id: project, email: { type: 'string', maxLength: 254 }, role: { type: 'string', enum: ['member', 'moderator', 'admin'] }, expected_revision: revision, client_request_id: requestId, approved: { type: 'boolean', const: true } }, ['owner_ref', 'project_id', 'email', 'role', 'expected_revision', 'client_request_id', 'approved']) },
   { name: 'list_my_project_agents', description: 'List only your own registered agent identities in a project you own. Returns authoritative IDs/names for selecting a team; not worker or online status.', annotations: { readOnlyHint: true }, inputSchema: object({ owner_ref: ownerRef, project_id: project }, ['owner_ref','project_id']) },
-  { name: 'register_my_project_agents', description: 'After the human approves the exact team names, atomically register 1–10 identities under that human account in its owned project. Retry the same names and client_request_id after lost replies. Creates no connection, worker, model, folder or GitHub changes. New owner approval must include register_own_agents. Use returned IDs for separate batch connection approval.', inputSchema: object({ owner_ref: ownerRef, project_id: project, names: { type:'array', minItems:1, maxItems:10, uniqueItems:true, items:{type:'string',pattern:'^[\\w-]{1,64}$'} }, client_request_id:requestId, approved:{type:'boolean',const:true} }, ['owner_ref','project_id','names','client_request_id','approved']) },
+  { name: 'register_my_project_agents', description: 'After the human approves the exact team names, atomically register 1–10 identities under that human account in its owned project. Retry the same names and client_request_id after lost replies. Creates no connection, worker, model, folder or GitHub changes. Connect them afterwards with connect_project_agents and the returned IDs; there is no browser step.', inputSchema: object({ owner_ref: ownerRef, project_id: project, names: { type:'array', minItems:1, maxItems:10, uniqueItems:true, items:{type:'string',pattern:'^[\\w-]{1,64}$'} }, client_request_id:requestId, approved:{type:'boolean',const:true} }, ['owner_ref','project_id','names','client_request_id','approved']) },
+  { name: 'set_agent_work_settings', description: 'Save the limits one of your human’s own agents starts under, after the human chose them: how involved they want to be and how long it may run. They become the defaults offered next time and are shown on My agents. Starts nothing.', inputSchema: object({ owner_ref: ownerRef, project_id: project, agent_id: { type: 'string', pattern: '^[\\w-]{1,200}$' }, involvement: { type: 'string', enum: ['with_me', 'on_own'], description: 'with_me: works in this conversation. on_own: works on its own as a supervised worker and reports at the end.' }, minutes: { type: 'integer', minimum: 15, maximum: 240, multipleOf: 15 } }, ['owner_ref', 'project_id', 'agent_id', 'involvement', 'minutes']) },
+  { name: 'add_project_agent', description: 'Add and connect one agent of your human’s in a project they belong to, through this computer’s one-time approval; no browser step. Use when the human asks for an agent in a project. Creates the named agent when it does not exist. Returns a connection_ref, the agent’s own folder and the repository to clone there; verify the reference with get_project. Starts no model and clones nothing. An agent already connected from another computer keeps that connection: add one under a new name instead.', inputSchema: object({ owner_ref: ownerRef, project_name: { type: 'string', minLength: 1, maxLength: 500, description: 'The project as the human named it. It is matched against the projects they belong to; when none or several match, the reply lists them.' }, project_id: { ...project, description: 'The exact project ID, instead of project_name, when it is already known.' }, agent_name: { type: 'string', pattern: '^[\\w-]{1,64}$' }, folder: { type: 'string', description: 'Leave out: the agent gets its own folder in the Karma42 layout, ~/karma42/projects/<project>/<agent>-<id>, named in the reply. Set an absolute folder only when the human asks for a different place.' } }, ['owner_ref', 'agent_name']) },
   { name: 'disconnect_owner_account', description: 'Revoke this saved human management connection. Agent bindings and running agents are separate and remain unchanged.', inputSchema: object({ owner_ref: ownerRef }, ['owner_ref']) },
 ];
+// The one question asked before an agent starts, in the shape a client's question tool takes.
+export function startQuestion(agentName, projectName, settings) {
+  const minutes = Number.isInteger(settings?.minutes) ? settings.minutes : 60, hours = minutes / 60;
+  const length = minutes < 60 ? `${minutes} minutes` : minutes % 60 ? `${Math.floor(hours)} h ${minutes % 60} min` : hours === 1 ? '1 hour' : `${hours} hours`;
+  const how = settings?.involvement === 'with_me' ? 'works with you in this conversation' : 'runs on its own';
+  return { question: `Start ${agentName} on ${projectName ?? 'this project'}? It ${how}, for up to ${length}.`, options: ['Yes, start', 'Change the limits', 'Not now'] };
+}
 export function ownerOrigin(site) {
   const u = new URL(site ?? process.env.KARMA42_SITE_URL ?? 'https://karma42.ai');
   if (u.username || u.password || u.search || u.hash || u.pathname !== '/' || !(u.protocol === 'https:' && ['karma42.ai', 'karma42-beta.web.app'].includes(u.hostname) && !u.port || u.protocol === 'http:' && ['127.0.0.1', 'localhost'].includes(u.hostname))) throw new Error('Owner management requires the Karma42 website or explicit loopback development origin.');
   return u.origin;
 }
-export function createOwnerClient({ home = sessionHome(), site, fetchImpl = fetch, now = Date.now } = {}) {
-  const origin = ownerOrigin(site); home = canonicalPath(home);
+export function createOwnerClient({ home = sessionHome(), workspace = workspaceHome(), site, fetchImpl = fetch, now = Date.now } = {}) {
+  const origin = ownerOrigin(site); home = canonicalPath(home); workspace = canonicalPath(workspace);
   function directory() { ensureHome(home); const root = join(home, 'owners'); privateDir(root); const dir = join(root, digest(origin)); privateDir(dir); return dir; }
   function receipt() {
     const p = join(directory(), 'owner.json'); if (!lstatExists(p)) return null;
@@ -41,6 +53,15 @@ export function createOwnerClient({ home = sessionHome(), site, fetchImpl = fetc
     return r;
   }
   const save = r => writePrivate(join(directory(), 'owner.json'), r);
+  // The one check behind every action that needs this computer's approval. It answers with the saved
+  // approval, or stops with the same instruction whether the computer was never approved or its approval
+  // ran out or was ended on My agents.
+  const NOT_APPROVED = `This computer is not approved for Karma42, or its approval has ended. Call connect_owner_account: your human approves this computer once in the browser, then repeat this call. Setup instructions: ${new URL('/viewer/?view=agents', origin).href}`;
+  function approved() {
+    const r = receipt();
+    if (!r || r.status !== 'approved' || r.connectionExpiresAt <= now()) throw new Error(NOT_APPROVED);
+    return r;
+  }
   async function request(path, { method = 'GET', body, token, poll } = {}) {
     let response;
     try { response = await fetchImpl(new URL('/api/owner' + path, origin), { method, redirect: 'error', credentials: 'omit', signal: AbortSignal.timeout(15000), headers: { Accept: 'application/json', ...(body ? { 'content-type': 'application/json' } : {}), ...(token ? { Authorization: `Bearer ${token}` } : {}), ...(poll ? { Authorization: `Bearer ${poll}` } : {}) }, ...(body ? { body: JSON.stringify(body) } : {}) }); }
@@ -51,27 +72,30 @@ export function createOwnerClient({ home = sessionHome(), site, fetchImpl = fetc
     if (!data || typeof data !== 'object' || Array.isArray(data)) throw new Error('Owner service returned an invalid response.');
     if (!response.ok) {
       const detail = response.status < 500 && typeof data.message === 'string' && data.message.length <= 500 && !/[\x00-\x1f\x7f-\x9f]/.test(data.message) ? data.message : null;
-      throw new Error(response.status === 401 ? 'Owner account authorization expired or was revoked. Sign in again.' : detail ? `Owner operation refused: ${detail}` : 'Owner operation refused. Read current status and review the original request before retrying.');
+      // The service no longer accepts this computer's approval: remember that, so the next call asks for a new one.
+      // Any other refusal, such as a project the person does not belong to, leaves the approval as it is.
+      if (response.status === 401 && token && /^This computer approval /.test(data.message ?? '')) { const r = receipt(); if (r?.token === token && r.status === 'approved') save({ ...r, status: 'revoked' }); throw new Error(NOT_APPROVED); }
+      throw new Error(detail ? `Owner operation refused: ${detail}` : 'Owner operation refused. Read current status and review the original request before retrying.');
     }
     return data;
   }
   function publicState(r) {
     const url = new URL('/viewer/', origin); url.searchParams.set('view','owner-connect'); url.searchParams.set('request',r.requestId);
-    return { status: r.status, owner_id: digest(origin), account_name: r.personName ?? null, expires_at: r.connectionExpiresAt ?? r.expiresAt ?? null, ...(r.status === 'pending' ? { approval_url: url.href, request_check: r.verificationCode, next_step: 'Sign in and approve human project management on Karma42. Then finish this same connection.' } : {}), scope: r.scopes ?? ['read_projects','start_projects','manage_project_roles'], agent_work_started: false };
+    return { status: r.status, owner_id: digest(origin), account_name: r.personName ?? null, expires_at: r.connectionExpiresAt ?? r.expiresAt ?? null, ...(r.status === 'pending' ? { approval_url: url.href, request_check: r.verificationCode, next_step: 'Sign in and approve this computer on Karma42, once. Then finish this same connection.' } : {}), agent_work_started: false };
   }
   async function connect(clientName = 'Karma42 CLI') {
-    return withBrowserLock(directory(), async () => {
+    return withOperationLock(directory(), async () => {
       let r = receipt();
       if (r?.status === 'approved' && r.connectionExpiresAt > now()) return publicState(r);
-      if (!r || ['expired','cancelled','revoked','approved'].includes(r.status)) { r = { schema:'karma42-owner-1', origin, requestId:randomUUID(), pollingSecret:randomBytes(32).toString('base64url'), token:randomBytes(32).toString('base64url'), clientName, registerOwnAgents:true, status:'pending' }; save(r); }
-      const response = await request('/connect', { method:'POST', body:{ requestId:r.requestId, pollingSecret:r.pollingSecret, candidateTokenHash:hash(r.token), clientName:r.clientName, registerOwnAgents:r.registerOwnAgents===true } });
+      if (!r || ['expired','cancelled','revoked','approved'].includes(r.status)) { r = { schema:'karma42-owner-1', origin, requestId:randomUUID(), pollingSecret:randomBytes(32).toString('base64url'), token:randomBytes(32).toString('base64url'), clientName, status:'pending' }; save(r); }
+      const response = await request('/connect', { method:'POST', body:{ requestId:r.requestId, pollingSecret:r.pollingSecret, candidateTokenHash:hash(r.token), clientName:r.clientName } });
       if (response.requestId !== r.requestId || !['pending','approved','expired','cancelled'].includes(response.status)) throw new Error('Owner service returned an invalid connection response. Retry this saved request.');
-      r = { ...r, status:response.status === 'approved' ? 'pending' : response.status, expiresAt:response.expiresAt, verificationCode:response.verificationCode, ...(Array.isArray(response.scopes) ? {scopes:response.scopes} : {}) }; save(r);
+      r = { ...r, status:response.status === 'approved' ? 'pending' : response.status, expiresAt:response.expiresAt, verificationCode:response.verificationCode }; save(r);
       return publicState(r);
     });
   }
   async function finish() {
-    return withBrowserLock(directory(), async () => {
+    return withOperationLock(directory(), async () => {
       const r = receipt(); if (!r) throw new Error('Owner connection has not been requested. Connect your human account first.');
       if (r.status === 'approved' && r.connectionExpiresAt > now()) return publicState(r);
       const response = await request(`/connect/${r.requestId}`, { poll:r.pollingSecret });
@@ -80,8 +104,8 @@ export function createOwnerClient({ home = sessionHome(), site, fetchImpl = fetc
     });
   }
   async function operation(name, args) {
-    const r = receipt(); if (!r || r.status !== 'approved' || r.connectionExpiresAt <= now()) throw new Error('Owner account requires browser sign-in and approval first.');
-    const specs = { list_my_project_agents:[`/projects/${args.project_id}/agents`], register_my_project_agents:[`/projects/${args.project_id}/agents`,'POST'], list_my_projects:['/projects'], list_my_proposals:['/proposals'], get_my_proposal:[`/proposals/${args.project_id}`], get_owned_project_status:[`/projects/${args.project_id}/status`], list_owned_project_members:[`/projects/${args.project_id}/members`], start_owned_project:[`/projects/${args.project_id}/start`,'POST'], set_owned_project_role:[`/projects/${args.project_id}/members`,'POST'], disconnect_owner_account:['/connections/revoke','POST'] };
+    const r = approved();
+    const specs = { set_agent_work_settings:[`/projects/${args.project_id}/agents/${args.agent_id}/settings`,'POST'], list_my_project_agents:[`/projects/${args.project_id}/agents`], register_my_project_agents:[`/projects/${args.project_id}/agents`,'POST'], list_my_projects:['/projects'], list_my_proposals:['/proposals'], get_my_proposal:[`/proposals/${args.project_id}`], get_owned_project_status:[`/projects/${args.project_id}/status`], list_owned_project_members:[`/projects/${args.project_id}/members`], start_owned_project:[`/projects/${args.project_id}/start`,'POST'], set_owned_project_role:[`/projects/${args.project_id}/members`,'POST'], disconnect_owner_account:['/connections/revoke','POST'] };
     if (!specs[name]) throw new Error('Owner operation is unknown.');
     if ((name.includes('owned_project') || name === 'get_my_proposal' || name === 'list_my_project_agents' || name === 'register_my_project_agents') && !ID.test(args.project_id ?? '')) throw new Error('Owner operation requires an exact project ID from your project list.');
     const schema = OWNER_TOOLS.find(t=>t.name===name).inputSchema;
@@ -94,9 +118,12 @@ export function createOwnerClient({ home = sessionHome(), site, fetchImpl = fetc
       if (name === 'start_owned_project') { if (args.start_without_minimum !== undefined && typeof args.start_without_minimum !== 'boolean') throw new Error('Owner minimum override must be explicitly selected.'); if (args.start_without_minimum !== undefined) body.start_without_minimum=args.start_without_minimum; }
       else { if (!['member','moderator','admin'].includes(args.role) || typeof args.email !== 'string' || args.email.length>254 || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(args.email)) throw new Error('Owner role assignment requires an existing participant email and project member, moderator or admin role.'); Object.assign(body,{ email:args.email,role:args.role,remove:false }); }
     }
+    if (name === 'set_agent_work_settings') {
+      if (!ID.test(args.project_id ?? '') || !/^[\w-]{1,200}$/.test(args.agent_id ?? '') || !['with_me','on_own'].includes(args.involvement) || !Number.isInteger(args.minutes) || args.minutes < 15 || args.minutes > 240 || args.minutes % 15 !== 0) throw new Error('Owner work settings need the exact project and agent IDs, an involvement of with_me or on_own, and 15–240 minutes in 15-minute steps.');
+      body = { involvement:args.involvement, minutes:args.minutes };
+    }
     if (name === 'register_my_project_agents') {
       if (args.approved !== true || !/^[\w-]{1,64}$/.test(args.client_request_id ?? '') || !Array.isArray(args.names) || args.names.length < 1 || args.names.length > 10 || new Set(args.names).size !== args.names.length || args.names.some(n => typeof n !== 'string' || !/^[\w-]{1,64}$/.test(n))) throw new Error('Owner team registration requires approved distinct names and the original request ID.');
-      if (!r.scopes?.includes('register_own_agents')) throw new Error('Owner connection did not approve agent registration. Disconnect it and approve a new owner connection including that permission.');
       body = { names:args.names,client_request_id:args.client_request_id,approved:true };
     }
     if (name === 'disconnect_owner_account') body = {};
@@ -105,5 +132,102 @@ export function createOwnerClient({ home = sessionHome(), site, fetchImpl = fetc
     if (name === 'disconnect_owner_account') save({...r,status:'revoked'});
     return response;
   }
-  return { connect,finish,operation };
+  // The projects the human belongs to, by name.
+  async function memberProjects(token) {
+    const projects = [];
+    for (let cursor, pages = 0; pages < 10; pages++) {
+      const page = await request('/member-projects' + (cursor ? '?cursor=' + encodeURIComponent(cursor) : ''), { token });
+      if (!Array.isArray(page.projects)) throw new Error('Owner service returned an invalid project list.');
+      projects.push(...page.projects.filter(p => ID.test(p?.projectId ?? '') && typeof p.projectName === 'string'));
+      if (!(cursor = page.next)) break;
+    }
+    return projects;
+  }
+  // The project the human named. Punctuation and case are ignored, and a shorter name is accepted when it
+  // fits exactly one project.
+  async function namedProject(name, token) {
+    const plain = value => String(value).normalize('NFKD').toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim(), wanted = plain(name), projects = await memberProjects(token);
+    const exact = projects.filter(p => plain(p.projectName) === wanted), found = exact.length ? exact : wanted ? projects.filter(p => plain(p.projectName).includes(wanted)) : [];
+    if (found.length === 1) return found[0];
+    const names = (found.length ? found : projects).map(p => `“${p.projectName}”`).join(', ');
+    throw new Error(found.length ? `Owner projects matching that name: ${names}. Ask your human which one.` : `Owner account belongs to no project with that name. Their projects: ${names || 'none; they join one on Karma42 first'}.`);
+  }
+  // Every agent connection saved on this computer, read from its private records.
+  function savedAgents() {
+    const found = [];
+    if (!lstatExists(home)) return found;
+    for (const project of readdirSync(home)) {
+      if (!ID.test(project)) continue;
+      for (const agent of readdirSync(join(home, project))) {
+        const dir = join(home, project, agent);
+        if (!lstatExists(join(dir, 'connection.json')) || !lstatExists(join(dir, 'token'))) continue;
+        const record = readPrivate(join(dir, 'connection.json'), true), token = readPrivate(join(dir, 'token'));
+        if (record?.schema === 'mcp-connection-1' && typeof record.folder === 'string' && TOKEN.test(token)) found.push({ record, token });
+      }
+    }
+    return found;
+  }
+  // The project's folder in the fixed layout, named after the project. The agent's own folder inside it,
+  // <agent>-<id>, is known once the service has answered with the agent's ID.
+  async function placedProject(projectId, service, token, saved, projectName) {
+    const projects = layout(workspace).projects, inside = folder => dirname(dirname(folder)) === projects;
+    const placed = saved.filter(s => inside(s.record.folder)).map(s => ({ projectId: s.record.service === service ? projectId : s.record.service, folder: dirname(s.record.folder) }));
+    projectName ??= (await memberProjects(token)).find(p => p.projectId === projectId)?.projectName;
+    if (typeof projectName !== 'string') throw new Error('Owner account does not belong to this project. Nothing was saved.');
+    const folder = projectFolder(workspace, projectId, projectName, placed);
+    mkdirSync(folder, { recursive: true }); mkdirSync(layout(workspace).main, { recursive: true });
+    return folder;
+  }
+  // The credential is generated here and saved before the service hears of it, so a lost reply is
+  // retried with the same credential and the service answers it as the same connection.
+  // exact: the agent's ID, when the caller names an existing agent. own: the folder is the agent's own checkout.
+  async function addAgent(args, clientName = 'Karma42 CLI', { exact, own = true } = {}) {
+    const r = approved();
+    const named = args.project_id === undefined && typeof args.project_name === 'string' && args.project_name.trim() && args.project_name.length <= 500 ? await namedProject(args.project_name, r.token) : null;
+    if (named) args = { ...args, project_id: named.projectId };
+    if (Object.keys(args).some(k => !['project_id','project_name','agent_name','folder'].includes(k)) || !ID.test(args.project_id ?? '') || !/^[\w-]{1,64}$/.test(args.agent_name ?? '') || (args.folder !== undefined && (typeof args.folder !== 'string' || !isAbsolute(args.folder)))) throw new Error('Adding an agent needs the project’s name or exact ID and a short agent name; a folder, when given, must be absolute.');
+    const service = projectIdentity({ projectUrl: new URL(`/p/${args.project_id}`, origin).href, folder: workspace }).projectUrl;
+    const adds = join(directory(), 'adds'); privateDir(adds);
+    const path = join(adds, `${digest([args.project_id, args.agent_name])}.json`);
+    const once = async (known, saved) => {
+      let add = lstatExists(path) ? readPrivate(path, true) : null;
+      if (add && (add.projectId !== args.project_id || add.name !== args.agent_name || !TOKEN.test(add.candidateToken ?? ''))) throw new Error('Saved agent request is invalid. No credentials were changed.');
+      // An agent this computer already connected keeps its folder and its saved credential, so picking it
+      // up again in a new conversation changes nothing and the service answers it as the same connection.
+      // An unfinished request keeps what it chose, also when its record was saved just before it was interrupted.
+      const chosen = args.folder !== undefined ? canonicalPath(args.folder) : add ? add.folder ?? null : known?.record.folder ?? null;
+      const project = chosen ? null : add?.project ?? await placedProject(args.project_id, service, r.token, saved, named?.projectName);
+      assertStateOutsideWorkspace(home, chosen ?? project);
+      if (add && (add.folder ?? null) !== chosen) throw new Error('An unfinished request for this agent names another folder. Retry it with that folder, or choose another agent name.');
+      if (!add) { add = { projectId: args.project_id, name: args.agent_name, folder: chosen, project, candidateToken: (known && known.record.folder === chosen ? known.token : null) ?? randomBytes(32).toString('base64url') }; writePrivate(path, add); }
+      // A refusal is final, so its request is not kept: the next attempt starts from what is saved.
+      // For an agent placed in the layout the service is told the project's folder; the agent's is inside it.
+      const result = await request(`/projects/${args.project_id}/agents/connect`, { method: 'POST', token: r.token, body: { name: args.agent_name, candidateTokenHash: hash(add.candidateToken), clientName, folder: chosen ?? project, ...(exact ?? known?.record.agentId ? { agentId: exact ?? known.record.agentId } : {}) } })
+        .catch(error => { if (/^Owner operation refused: /.test(error.message)) unlinkSync(path); throw error; });
+      if (!/^[\w-]{1,200}$/.test(result.agentId ?? '') || result.agentName !== args.agent_name || result.projectId !== args.project_id || ((exact ?? known?.record.agentId) && result.agentId !== (exact ?? known.record.agentId))) throw new Error('Owner service returned a different agent than requested. Nothing was saved; review My agents.');
+      const folder = chosen ?? join(project, `${args.agent_name}-${result.agentId.slice(0, 6).toLowerCase()}`);
+      assertStateOutsideWorkspace(home, folder);
+      const id = sessionId(service, result.agentId), dir = connectionDir(home, id);
+      // An agent this conversation's own process keeps connected is already saved with this credential:
+      // nothing is written, and its lock is this process's own.
+      const lock = join(dir, 'operation.lock'), here = known?.record.id === id && known.record.folder === folder && known.token === add.candidateToken && lstatExists(lock) && readPrivate(lock).trim() === String(process.pid);
+      const record = here ? validateSession(known.record, id) : validateSession({ schema: 'mcp-connection-1', id, service, agentId: result.agentId, agentName: result.agentName, repo: projectIdentity({ projectUrl: service, repo: result.repoUrl, folder }).repo, folder, createdAt: now(), approvedAt: now(), ...(own ? { ownFolder: true } : {}) }, id);
+      if (!here) await withOperationLock(dir, async () => {
+        writePrivate(join(dir, 'token'), add.candidateToken); saveConnection(dir, record);
+      });
+      unlinkSync(path);
+      return { record, repo: record.repo, created: result.created === true, settings: result.settings ?? null, project_name: typeof result.projectName === 'string' ? result.projectName : null };
+    };
+    return withOperationLock(directory(), async () => {
+      const saved = savedAgents(), known = saved.find(s => s.record.service === service && s.record.agentName === args.agent_name) ?? null;
+      try { return await once(known, saved); }
+      catch (error) {
+        // The saved record belongs to an agent the service no longer has under this name, such as one revoked on
+        // My agents. It is left alone and the name is added as a new agent, with a new credential and folder.
+        if (!known || exact || !/^Owner operation refused: You have no agent with this ID and name/.test(error.message)) throw error;
+        return once(null, saved);
+      }
+    });
+  }
+  return { origin,connect,finish,operation,addAgent };
 }