@open-everywhere/core 0.1.0

package/agent/connections/own-account-ask.ts

@@ -0,0 +1,302 @@
+// The "use my own account" ask, and the ACTING IDENTITY it decides. Once an account is named, no arm falls
+// back to the `install` credential: a silent substitution answers a member's question with the org's view.
+
+// TYPE-ONLY, so this module stays import-free at runtime and closes no cycle: the access plane's
+// catalogue module is a heavy leaf, and a value import here would drag it into every provider read.
+import type { CredentialGrantFamily } from "../access/connector-credentials.js";
+
+/** One vendor, as the grammar recognises it: the connector id plus the words a person writes for it. */
+export interface OwnAccountVendor {
+  /** The connector id the rest of the access plane uses, e.g. `notion`. */
+  readonly connector: string;
+  /** Lower-case words a person writes for this vendor. The connector id itself need not be repeated. */
+  readonly aliases?: readonly string[];
+}
+
+/**
+ * A recognised ask. 🔴 It carries NO member words: the audit record is append-only with no delete path, so a
+ * quoted sentence would sit outside the erasure path forever. It records THAT an ask was recognised.
+ */
+export interface OwnAccountAsk {
+  readonly connector: string;
+  /**
+   * The same sentence also named the TEAM's account, so which identity the member meant cannot be
+   * read off it. Refused rather than resolved — see {@link decideActingIdentity}.
+   */
+  readonly ambiguous: boolean;
+}
+
+/** The ACCOUNT noun. Deliberately short and singular: every plural and every abstract noun that was
+ *  tried here ("accounts", "identity", "workspace access") matched ordinary business language. */
+const ACCOUNT_NOUN_RE = "(?:account|login|credential|credentials|oauth|token)";
+
+/**
+ * First-person possession of an account, WITHOUT naming the vendor. 🔴 NO FILLER between the possessive and
+ * the noun: a possessive clause that names some other account holder is not this vendor's ask.
+ */
+const OWN_POSSESSIVE_RE = new RegExp(String.raw`\bmy\s+(?:own|personal)\s+${ACCOUNT_NOUN_RE}\b`);
+
+/**
+ * How far from a vendor-free possessive clause the vendor's own name may sit and still be ITS name. The
+ * clause must be BOUND to the vendor, or "my own account at the bank" refuses a Notion read.
+ */
+const VENDOR_ADJACENCY_WORDS = 3;
+
+/** The one shape that makes a sentence AMBIGUOUS: it also names the team/org/shared account. A
+ *  member who writes "use my own account, not the team account" has named both, and picking either
+ *  silently is the defect in one direction or a broken tool in the other. */
+const TEAM_ACCOUNT_RE =
+  /\b(?:team|org|organisation|organization|shared|company|workspace|deployment|default)(?:'s)?\s+(?:\S+\s+)?(?:account|integration|credential|credentials|key|token|login)\b/;
+
+/** Sentence split, on terminators and newlines. The grammar's window is ONE sentence: "read my own
+ *  page. Use Notion." names no account with a vendor and must not be read as if it did. */
+function sentencesOf(text: string): readonly string[] {
+  return text
+    .split(/(?<=[.!?;])\s+|\n+/)
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+/** The words that name `vendor` — its connector id plus whatever aliases it declares, lower-cased,
+ *  regex-escaped (an alias like `notion.so` carries a metacharacter). */
+function vendorWords(vendor: OwnAccountVendor): readonly string[] {
+  return [vendor.connector, ...(vendor.aliases ?? [])]
+    .map((w) => w.toLowerCase())
+    .filter((w) => w.length > 0)
+    .map((w) => w.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+}
+
+/** `my <vendor> <account noun>` — the arm that lets bare `my` match, and only when the VENDOR's own
+ *  name sits between it and the noun. That is what tells "my notion account" from "my account
+ *  manager". */
+function vendorPossessiveRe(vendor: OwnAccountVendor): RegExp {
+  return new RegExp(String.raw`\bmy\s+(?:own\s+|personal\s+)?(?:${vendorWords(vendor).join("|")})\s+${ACCOUNT_NOUN_RE}\b`);
+}
+
+/**
+ * Is a vendor-free possessive clause bound to THIS vendor by adjacency? The window is words, counted out
+ * from the clause in both directions. A vendor word INSIDE the clause is arm A's business, not this one's.
+ */
+function possessiveBoundToVendor(lower: string, vendor: OwnAccountVendor): boolean {
+  const match = OWN_POSSESSIVE_RE.exec(lower);
+  if (match === null) return false;
+  const before = lower.slice(0, match.index).split(/\s+/).filter(Boolean).slice(-VENDOR_ADJACENCY_WORDS);
+  const after = lower
+    .slice(match.index + match[0].length)
+    .split(/\s+/)
+    .filter(Boolean)
+    .slice(0, VENDOR_ADJACENCY_WORDS);
+  const window = [...before, ...after].join(" ");
+  return vendorWords(vendor).some((w) => new RegExp(w).test(window));
+}
+
+/**
+ * Does this sentence name `vendor` AND ask for the requester's own account with it? 🔴 The possessive is
+ * BOUND to the vendor, never merely co-resident: arm A names it inside the clause, arm B requires adjacency.
+ */
+function sentenceNamesOwnAccount(sentence: string, vendor: OwnAccountVendor): boolean {
+  const lower = sentence.toLowerCase();
+  if (!vendorWords(vendor).some((w) => new RegExp(w).test(lower))) return false;
+  return vendorPossessiveRe(vendor).test(lower) || possessiveBoundToVendor(lower, vendor);
+}
+
+/**
+ * Which vendor the requester asked to act AS THEMSELVES for. 🔴 `messages` must be ONE person's own words:
+ * handing it tool output or an envelope would let somebody else's text ask for this requester's credential.
+ */
+export function namedOwnAccountVendor(messages: readonly string[], vendors: readonly OwnAccountVendor[]): OwnAccountAsk | undefined {
+  for (const message of messages) {
+    for (const sentence of sentencesOf(message)) {
+      for (const vendor of vendors) {
+        if (!sentenceNamesOwnAccount(sentence, vendor)) continue;
+        return { ambiguous: TEAM_ACCOUNT_RE.test(sentence.toLowerCase()), connector: vendor.connector };
+      }
+    }
+  }
+  return undefined;
+}
+
+/** Why the acting identity came out the way it did — the `why` half of the audit row, and a closed
+ *  set so a reader can count rows by reason rather than by parsing a sentence. */
+export type ActingIdentityReason =
+  /** No requester sentence named an account. The ordinary path, and unchanged behaviour. */
+  | "no-own-account-ask"
+  /** The requester named their own account and this chat holds a live personal grant for the vendor. */
+  | "own-account-ask-grant-held"
+  /** The requester named their own account and no personal grant exists. REFUSED. */
+  | "own-account-ask-no-grant"
+  /** One sentence named their own account AND the team's. REFUSED, with a question back. */
+  | "own-account-ask-ambiguous";
+
+/**
+ * The gate's answer. 🔴 `identity` is absent exactly when `refusal` is present: `requiredIdentity` is what
+ * the REQUEST needs, `identity` is what the caller may run under. A caller keys on `refusal` first.
+ */
+export interface ActingIdentityVerdict {
+  /** What the request requires. Always present, and what the audit row reports. */
+  readonly requiredIdentity: CredentialGrantFamily;
+  /** What the caller may run under. Present iff `refusal` is absent. */
+  readonly identity?: CredentialGrantFamily;
+  readonly reason: ActingIdentityReason;
+  /** The sentence to give the model, present iff the call is refused. */
+  readonly refusal?: string;
+  /** An own-account ask was recognised this turn. Audit material — never the words themselves. */
+  readonly askRecognised: boolean;
+}
+
+/** What the caller knows about the routes out of a refusal. All facts about THIS chat, resolved by
+ *  the gate, never guessed here. */
+export interface ActingIdentityInput {
+  readonly connector: string;
+  /** The recognised ask, or undefined when the requester named no account. */
+  readonly ask?: OwnAccountAsk;
+  /** This chat holds a live personal grant for `connector`. */
+  readonly personalGrantHeld: boolean;
+  /**
+   * The personal-consent route can be raised from here at all. 🔴 It changes the SENTENCE, never the verdict:
+   * both arms refuse, and offering a route that is not mounted is the same silent failure one layer up.
+   */
+  readonly consentRouteAvailable: boolean;
+  /**
+   * The DEPLOYMENT half of the consent route. It separates a FIXABLE absence from a structural one: naming a
+   * domain fix for a vendor this tree lends nothing for sends an operator to a config that cannot help.
+   */
+  readonly deploymentAdmitsGrant: boolean;
+  /**
+   * THIS caller can issue the call under the requester's OWN credential. False for every team-credential read
+   * tool here: a personal grant is spent by the mounted `grant__…` tool, so a held grant does not let this run.
+   */
+  readonly callerCanSpendPersonal: boolean;
+}
+
+/**
+ * The decision, and the one place the four arms are written down. 🔴 No arm answers an own-account ask with
+ * the `install` identity — that combination is the defect, not a fallback and not the ambiguous answer.
+ */
+export function decideActingIdentity(input: ActingIdentityInput): ActingIdentityVerdict {
+  if (input.ask === undefined) return { askRecognised: false, identity: "install", reason: "no-own-account-ask", requiredIdentity: "install" };
+  // AMBIGUOUS FIRST. A sentence naming both accounts cannot be resolved by reading it harder, and
+  // the shipped behaviour it would otherwise fall back to IS the defect — so it asks.
+  if (input.ask.ambiguous) {
+    return {
+      askRecognised: true,
+      reason: "own-account-ask-ambiguous",
+      refusal: ambiguousAccountRefusal(input.connector),
+      requiredIdentity: "human-acting",
+    };
+  }
+  if (input.personalGrantHeld) {
+    return {
+      askRecognised: true,
+      reason: "own-account-ask-grant-held",
+      requiredIdentity: "human-acting",
+      ...(input.callerCanSpendPersonal ? { identity: "human-acting" as const } : { refusal: personalRouteRefusal(input.connector) }),
+    };
+  }
+  return {
+    askRecognised: true,
+    reason: "own-account-ask-no-grant",
+    refusal: ownAccountRefusal(input.connector, input.consentRouteAvailable, input.deploymentAdmitsGrant),
+    requiredIdentity: "human-acting",
+  };
+}
+
+/**
+ * What the model is told when an own-account ask has no personal grant behind it. It is an instruction to
+ * SPEAK, not an error to retry, and there are THREE route sentences because a member acts on each state.
+ */
+export function ownAccountRefusal(connector: string, consentRouteAvailable: boolean, deploymentAdmitsGrant: boolean): string {
+  const opening =
+    `Refused: this request asks to act with the requester's own ${connector} account, and this chat holds no personal ` +
+    `${connector} grant. Reading under the deployment's ${connector} integration would answer as the org, not as them, ` +
+    `and they would have no way to see the difference.`;
+  const route = consentRouteAvailable
+    ? `Hand this to a task: the task raises the ask with \`request_credential_grant\`, which lives there and nowhere else. ` +
+      `Then tell the room the ask went out.`
+    : deploymentAdmitsGrant
+      ? `This chat cannot raise a personal ${connector} grant — no domain here admits one — so there is no consent flow to start.`
+      : `This deployment cannot lend a personal ${connector} account at all: ${connector} admits no credential grant, so ` +
+        `there is no consent flow to start and no domain setting opens one. Do not tell them to connect their account.`;
+  const fallback =
+    `Otherwise say plainly, in the room, that you cannot act as them on ${connector}, and that you will use the shared ` +
+    `${connector} integration only if they agree to it. Do not read under the shared integration until they say so.`;
+  return `${opening} ${route} ${fallback}`;
+}
+
+/**
+ * What the model is told when one sentence named BOTH accounts. It asks rather than guessing: both guesses
+ * are wrong in a way the member cannot see from the answer.
+ */
+export function ambiguousAccountRefusal(connector: string): string {
+  return (
+    `Refused: this request names the requester's own ${connector} account AND the shared ${connector} integration in one ` +
+    `sentence, so which account to act with cannot be read off it. Ask them in the room which they mean. Do not choose ` +
+    `for them — the two see different pages, and the answer would not say which one it came from.`
+  );
+}
+
+/**
+ * What the model is told when the account IS lent to this chat but the calling tool has no arm to spend it.
+ * It names the route: the granted `grant__…` tool is the one that runs under their credential.
+ */
+export function personalRouteRefusal(connector: string): string {
+  return (
+    `Refused: this request asks to act with the requester's own ${connector} account, and they have already lent it to ` +
+    `this chat. This tool reads under the deployment's shared ${connector} integration, so running it here would answer ` +
+    `as the org after they said "as me". The granted \`grant__…_${connector}__…\` tool is the one that runs under their ` +
+    `credential, and it lives on this conversation's TASKS. Hand the read to a task.`
+  );
+}
+
+/**
+ * The audit action written at the DECISION POINT — the moment the host recognises that this delivery asks
+ * the agent to act with the requester's own account. 🔴 IT IS NOT A SECOND COPY OF
+ * `connector.acting_identity`, and the difference is the whole point: that row is written per
+ * gated connector READ, so a turn the seat answers by refusing WITHOUT reading writes none at all. Refusing
+ * without reading is the CORRECT outcome (own-account = honest refusal), and until this row it was the one
+ * outcome no auditor and no e2e leg could observe — an absence that reads exactly like a turn that never
+ * happened. The two rows join on the turn: this one says a person asked, the acting-identity rows say which
+ * credential each read then chose.
+ */
+export const CONNECTOR_OWN_ACCOUNT_ASK_ACTION = "connector.own_account_ask";
+
+/** What an own-account ask REQUIRES, restated on the recognition row. The credential choice has not been
+ *  made at this point — no grant has been read — so the row reports the requirement, never a grant. */
+const OWN_ACCOUNT_REQUIRED_IDENTITY: CredentialGrantFamily = "human-acting";
+
+/**
+ * The audit detail for one RECOGNISED own-account ask. 🔴 NO member words, ever — the same rule
+ * {@link actingIdentityAuditDetail} states, and for the same reason: the record has no delete path.
+ *
+ * `outcome` is the closed answer to "what must this turn do now", which is what makes the row scoreable
+ * on its own. It is NOT the credential the turn ended up spending: nothing has read a grant yet.
+ */
+export function ownAccountAskAuditDetail(ask: OwnAccountAsk, stamped: boolean): Record<string, unknown> {
+  return {
+    askRecognised: true,
+    connector: ask.connector,
+    // Recognition can only tell the two refusals apart — an ambiguous sentence is refused by reading it,
+    // and every other ask is refused unless this chat turns out to hold a live personal grant.
+    outcome: ask.ambiguous ? "refuse-ambiguous" : "refuse-unless-grant-held",
+    requiredIdentity: OWN_ACCOUNT_REQUIRED_IDENTITY,
+    /** The stamp reached this delivery's auth bag, so a worker dispatched later this turn inherits the ask.
+     *  `false` means only the SEAT's own words carry it — a delegated read would not see it. */
+    stamped,
+  };
+}
+
+/**
+ * The audit detail for one acting-identity decision: identifiers and a closed reason. 🔴 NO member words,
+ * ever — the record is append-only, so a quoted sentence would sit outside the erasure path forever.
+ */
+export function actingIdentityAuditDetail(verdict: ActingIdentityVerdict, connector: string, tool: string): Record<string, unknown> {
+  return {
+    askRecognised: verdict.askRecognised,
+    connector,
+    ...(verdict.identity === undefined ? {} : { identity: verdict.identity }),
+    reason: verdict.reason,
+    refused: verdict.refusal !== undefined,
+    requiredIdentity: verdict.requiredIdentity,
+    tool,
+  };
+}

package/agent/connections/own-account-carriage.ts

@@ -0,0 +1,99 @@
+// THE WIRE HALF of the own-account gate: a host-set auth attribute carries a recognised ask to a delegated
+// worker, which has no requester words of its own. It carries identifiers and one flag — never a sentence.
+
+import { classifySessionId } from "../channels/window-key.js";
+import { currentTurnId, delegationRootSessionId, type BindableContext } from "../identity/binding.js";
+import type { OwnAccountAsk } from "./own-account-ask.js";
+
+/** Auth attribute carrying a recognised own-account ask. Host-set, model-unforgeable (see
+ *  channels/unified-window.ts §AUTH-ATTRIBUTE PROVENANCE). */
+export const OE_OWN_ACCOUNT_ASK_ATTR = "oe_own_account_ask";
+
+/** The flag an AMBIGUOUS ask (one naming the team's account too) adds to the stamp's fourth field. */
+const AMBIGUOUS_FLAG = "ambiguous";
+
+/**
+ * The stamp's TURN half when the producer could not read a turn id. 🔴 A named absence, not an empty field:
+ * it keeps the wire shape unambiguous against a session id holding a `|`, and no real turn id collides.
+ */
+export const TURN_UNKNOWN = "-";
+
+/**
+ * The stamp's wire shape: `<sessionId>|<turnId>|<connector>`, plus `|ambiguous` when the sentence named the
+ * team's account too. Identifiers and one flag — never the sentence. `turnId` is {@link TURN_UNKNOWN} where the
+ * producer could not read one, and {@link turnHalfAdmits} states when the turn half is compared at all.
+ */
+export function renderOwnAccountStamp(sessionId: string, turnId: string | undefined, ask: OwnAccountAsk): string {
+  const turn = turnId !== undefined && turnId.length > 0 ? turnId : TURN_UNKNOWN;
+  return `${sessionId}|${turn}|${ask.connector}${ask.ambiguous ? `|${AMBIGUOUS_FLAG}` : ""}`;
+}
+
+/**
+ * The stamp's fields, or undefined when the value is not a shape this build wrote. 🔴 A stamp from an older
+ * build resolves undefined and reads as NO ask — today's behaviour, and the safe floor.
+ */
+export function parseOwnAccountStamp(
+  raw: string | undefined,
+): { readonly sessionId: string; readonly turnId: string; readonly ask: OwnAccountAsk } | undefined {
+  if (raw === undefined) return undefined;
+  const parts = raw.split("|");
+  if (parts.length < 3 || parts.length > 4) return undefined;
+  const [sessionId, turnId, connector, flag] = parts;
+  if (!sessionId || !turnId || !connector) return undefined;
+  if (parts.length === 4 && flag !== AMBIGUOUS_FLAG) return undefined;
+  return { ask: { ambiguous: flag === AMBIGUOUS_FLAG, connector }, sessionId, turnId };
+}
+
+/** Read the stamp off a context, tolerating eve's `string[]` collapse — the same read every other
+ *  stamp consumer in this tree does. */
+function readOwnAccountAttr(ctx: BindableContext): string | undefined {
+  const attrs = (ctx as { session?: { auth?: { current?: { attributes?: Record<string, unknown> } | null } } }).session?.auth?.current?.attributes;
+  const raw = attrs?.[OE_OWN_ACCOUNT_ASK_ATTR];
+  const first = Array.isArray(raw) ? raw[0] : raw;
+  return typeof first === "string" && first.length > 0 ? first : undefined;
+}
+
+/**
+ * The sessions a stamp may name for THIS context to adopt it. 🔴 The token arm is not redundant:
+ * `delegationRootSessionId` misses a dynamic-resolver context, and the token is the linkage every child has.
+ */
+function adoptableSessions(ctx: BindableContext): readonly string[] {
+  const out: string[] = [];
+  const own = (ctx as { session?: { id?: string } }).session?.id;
+  if (typeof own === "string" && own.length > 0) out.push(own);
+  const root = delegationRootSessionId(ctx);
+  if (root !== undefined && root.length > 0) out.push(root);
+  const classified = classifySessionId(ctx.channel?.continuationToken);
+  if (classified.kind === "subagent" && classified.parentSessionId.length > 0) out.push(classified.parentSessionId);
+  return out;
+}
+
+/**
+ * Does the stamp's TURN half admit this reader? It answers `true` wherever the comparison is not meaningful
+ * — another session, an unnameable turn, an unreadable turn — and compares only on the stamping session.
+ */
+function turnHalfAdmits(ctx: BindableContext, stamp: { readonly sessionId: string; readonly turnId: string }): boolean {
+  const own = (ctx as { session?: { id?: string } }).session?.id;
+  if (typeof own !== "string" || own !== stamp.sessionId) return true; // a delegation arm
+  if (stamp.turnId === TURN_UNKNOWN) return true;
+  const now = currentTurnId(ctx);
+  if (now === undefined) return true;
+  return now === stamp.turnId;
+}
+
+/**
+ * The ask this session runs under, or undefined. THREE comparisons, and all must pass: the session half, the
+ * CONNECTOR half (else a Notion ask answers a Linear caller), and the turn half. Fail-soft to undefined.
+ */
+export function adoptedOwnAccountAsk(ctx: BindableContext, vendors: readonly { readonly connector: string }[]): OwnAccountAsk | undefined {
+  try {
+    const stamp = parseOwnAccountStamp(readOwnAccountAttr(ctx));
+    if (stamp === undefined) return undefined;
+    if (!vendors.some((v) => v.connector === stamp.ask.connector)) return undefined;
+    if (!adoptableSessions(ctx).includes(stamp.sessionId)) return undefined;
+    if (!turnHalfAdmits(ctx, stamp)) return undefined;
+    return stamp.ask;
+  } catch {
+    return undefined;
+  }
+}