@fargowealth/fargo-ai-cli 1.4.1 → 1.5.0

package/src/yida-operation.mjs

@@ -0,0 +1,64 @@
+import { lstat, mkdir, open, readFile, rename, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { createCredentialStore } from "./credential-store.mjs";
+
+export function extractYidaProcessId(result) {
+  if (result?.success !== true) throw new Error("YIDA_PROCESS_RESULT_UNVERIFIED");
+  const candidates = [result.processInstanceId, typeof result.content === "object" ? result.content?.processInstanceId : result.content,
+    typeof result.result === "object" ? result.result?.processInstanceId : result.result].filter(value => value !== undefined && value !== null);
+  if (!candidates.length || candidates.some(value => typeof value !== "string" || !/^[A-Za-z0-9_-]{1,200}$/.test(value)) || new Set(candidates).size !== 1) {
+    throw new Error("YIDA_PROCESS_RESULT_UNVERIFIED: reconcile before any new submission");
+  }
+  return candidates[0];
+}
+
+async function regular(path, directory = false) {
+  const value = await lstat(path);
+  if (value.isSymbolicLink() || !(directory ? value.isDirectory() : value.isFile()) ||
+      (typeof process.getuid === "function" && value.uid !== process.getuid())) throw new Error("YIDA_OPERATION_STORE_INVALID");
+}
+async function save(path, record) {
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  let handle;
+  try {
+    handle = await open(temporary, "wx", 0o600);
+    await handle.writeFile(`${JSON.stringify(record)}\n`);
+    await handle.sync();
+    await handle.close();
+    handle = undefined;
+    await rename(temporary, path);
+  } finally { await handle?.close(); await rm(temporary, { force: true }); }
+}
+
+// This is a local replay guard, not an upstream idempotency guarantee. Unknown
+// results require read-back; a second invocation must never create another instance.
+export async function runRecordedYidaMutation({ directory, requestId, payloadHash, send, allowSafeRetry = false }) {
+  if (!/^[a-zA-Z0-9_-]{1,100}$/.test(requestId) || !/^sha256:[a-f0-9]{64}$/.test(payloadHash)) throw new Error("YIDA_OPERATION_INVALID");
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  await regular(directory, true);
+  const file = join(directory, `${requestId}.json`);
+  const lock = createCredentialStore({ env: { FARGO_REFRESH_LOCK_PATH: join(directory, `${requestId}.lock`) } });
+  return lock.withRefreshLock(async () => {
+    let previous;
+    try { await regular(file); previous = JSON.parse(await readFile(file, "utf8")); }
+    catch (error) { if (error.code !== "ENOENT") throw error; }
+    if (previous) {
+      if (previous.payloadHash !== payloadHash) throw new Error("YIDA_OPERATION_CONFLICT: request ID already belongs to another payload");
+      if (previous.status === "accepted") return { ...previous.receipt, replayedFromReceipt: true };
+      if (!allowSafeRetry || previous.status !== "not_applied") throw new Error("YIDA_OPERATION_RESULT_UNKNOWN: do not resend; reconcile the recorded request first");
+    }
+    const record = { requestId, payloadHash, status: "sending", startedAt: new Date().toISOString() };
+    await save(file, record);
+    try {
+      const receipt = await send();
+      await save(file, { ...record, status: "accepted", receipt, completedAt: new Date().toISOString() });
+      return receipt;
+    } catch (error) {
+      // Opt-in only: a later explicit invocation can retry a proven pre-dispatch
+      // failure or authorization rejection. Timeouts/ambiguous responses stay blocked.
+      await save(file, { ...record, status: allowSafeRetry && error.yidaMutationNotApplied === true ? "not_applied" : "result_unknown", upstreamCode: error.upstreamCode ?? null });
+      throw error;
+    }
+  });
+}

package/src/yida-rules.mjs

@@ -0,0 +1,101 @@
+import { createHash } from "node:crypto";
+
+const hash = value => `sha256:${createHash("sha256").update(typeof value === "string" ? value : JSON.stringify(value)).digest("hex")}`;
+const refs = text => [...new Set([...String(text).matchAll(/#\{([^}]+)\}/g)].map(match => match[1]))];
+const object = value => { try { return typeof value === "string" ? JSON.parse(value) : value; } catch { return null; } };
+
+// Describe business configuration; never execute page JavaScript or formulas.
+export function modelYidaRules(content, appType) {
+  const rules = [], connectors = [], scripts = [], datasetQueries = [], pageBindings = [];
+  const seen = new Set();
+  let truncated = false, visited = 0;
+  function add(rule) {
+    const key = JSON.stringify([rule.fieldId, rule.kind, rule.expression]);
+    if (seen.has(key)) return;
+    seen.add(key);
+    if (rules.length >= 5000 || rule.expression?.length > 16000) { truncated = true; return; }
+    rules.push({ ...rule, inputs: refs(rule.expression), verification: "configuration_read_runtime_not_verified" });
+  }
+  function formula(props, value, kind, parentFieldId) {
+    if (!value || (typeof value === "string" && !value.trim())) return;
+    if (typeof value === "string") {
+      const relate = value.match(/^@\{\{(FORM-[A-Za-z0-9_-]+)\/([A-Za-z0-9_]+)\}\}$/);
+      if (relate) add({ fieldId: props.fieldId, parentFieldId, kind, expression: value,
+        source: { kind: "form_lookup", appType, formUuid: relate[1], fieldId: relate[2] }, lookupMode: "relate" });
+      else add({ fieldId: props.fieldId, parentFieldId, kind, expression: value });
+      return;
+    }
+    const config = value.data;
+    if (!config || typeof config !== "object" || Array.isArray(config)) return;
+    const events = Object.entries(value.event ?? {}).flatMap(([event, items]) => Array.isArray(items) ? items.map(item => ({ event, item })) : []);
+    const expressions = events.filter(({ item }) => typeof item.params?.value === "string" && item.params.target === props.fieldId);
+    for (const { item } of expressions) {
+      add({ fieldId: props.fieldId, parentFieldId, kind, expression: item.params.value,
+        source: { kind: "form_lookup", appType: config.appType ?? appType, formUuid: config.formId, fieldId: config.otherLinkageFieldId,
+          deduplicate: config.deduplication === true, conditions: config.conditions ?? null },
+        triggers: events.filter(x => x.item.params?.target === props.fieldId).map(x => ({ fieldId: x.item.fieldId, event: x.event })), lookupMode: "linkage" });
+    }
+  }
+  function visit(node, parentFieldId = null, depth = 0) {
+    if (!node || typeof node !== "object") return;
+    if (++visited > 10000 || depth > 100) { truncated = true; return; }
+    const props = node.props ?? {};
+    for (const key of ["formUuid", "formId", "targetFormUuid", "appType", "viewUuid"]) {
+      if (typeof props[key] === "string" && /^(?:FORM-|APP_|VIEW-)[A-Za-z0-9_-]+$/.test(props[key])) pageBindings.push({ componentId: node.id, componentName: node.componentName, property: key, value: props[key] });
+    }
+    for (const [dataSetKey, dataset] of Object.entries(props.dataSetModelMap ?? {})) {
+      if (!dataset || typeof dataset !== "object") continue;
+      const query = dataset.dataViewQueryModel ?? {};
+      datasetQueries.push({ componentId: node.id, componentName: node.componentName, cid: props.cid, dataSetKey,
+        cubeCodes: dataset.cubeCodes, limit: dataset.limit, configurationHash: hash(query),
+        fields: (query.fieldDefinitionList ?? []).map(field => ({ fieldCode: field.fieldCode, alias: field.alias, cubeCode: field.cubeCode,
+          aggregateType: field.aggregateType, timeGranularityType: field.timeGranularityType, dataType: field.dataType, isDim: field.isDim })),
+        selectedAliases: query.fieldList, filters: query.filterList, orderBy: query.orderByList, groupBy: query.groupByList,
+        verification: "configuration_read_runtime_not_verified" });
+    }
+    let parent = parentFieldId;
+    if (props.fieldId && /Field$/.test(node.componentName ?? "")) {
+      formula(props, props.formula, "calculation", parentFieldId);
+      formula(props, props.complexValue?.formula, props.complexValue?.complexType === "linkage" ? "linked_value" : "calculation", parentFieldId);
+      formula(props, props.defaultDataSource?.formula, "options", parentFieldId);
+      if (props.behavior && typeof props.behavior === "object") {
+        rules.push({ fieldId: props.fieldId, parentFieldId, kind: "visibility", binding: {
+          type: props.behavior.type, variable: props.behavior.variable, initialValue: props.behavior.value
+        }, verification: "configuration_read_runtime_not_verified" });
+      }
+      parent = props.fieldId;
+    }
+    for (const source of node.dataSource?.online ?? []) {
+      if (source.dpType !== "YIDACONNECTOR") continue;
+      const info = object(source.options?.params?.serviceInfo)?.connectorInfo;
+      if (!info) continue;
+      connectors.push({ name: source.name, kind: "configured_connector", connectorId: info.connectorId, actionId: info.actionId,
+        connection: info.connection, type: info.type, inputTemplateHash: hash(source.options?.params?.inputs ?? ""),
+        verification: "configuration_read_adapter_required" });
+    }
+    for (const child of Array.isArray(node.children) ? node.children : []) visit(child, parent, depth + 1);
+  }
+  for (const page of content.pages ?? []) for (const node of page.componentsTree ?? []) visit(node);
+  const code = content.actions?.module?.compiled ?? content.actions?.module?.source;
+  if (typeof code === "string" && code) scripts.push({ sha256: hash(code),
+    actionNames: [...new Set([...code.matchAll(/exports\.([A-Za-z_$][\w$]*)\s*=/g)].map(x => x[1]))],
+    referencedFieldIds: [...new Set(code.match(/(?:[A-Za-z]+Field)_[A-Za-z0-9_]+/g) ?? [])],
+    verification: "source_detected_manual_adapter_required", executableSourceIncluded: false });
+  return JSON.parse(JSON.stringify({ rules, connectors, scripts, datasetQueries, pageBindings, ruleCount: rules.length, truncated, formulasExecuted: false }));
+}
+
+export function compileYidaLookup(rule, values, appType) {
+  if (!rule?.source || rule.source.appType !== appType || !["options", "linked_value"].includes(rule.kind)) throw new Error("YIDA_RULE_UNSUPPORTED: no same-app configured lookup");
+  let expression;
+  if (rule.lookupMode === "relate") {
+    expression = `FETCHDISTINCTDATA(${JSON.stringify(rule.source.formUuid)},${JSON.stringify(rule.source.fieldId)},QUERYLIKECI(${JSON.stringify(rule.source.fieldId)},""),"1","100")`;
+  } else {
+    expression = rule.expression.replace(/#\{([^}]+)\}/g, (_match, fieldId) => {
+      if (!Object.hasOwn(values, fieldId)) throw new Error(`YIDA_RULE_INPUT_REQUIRED: ${fieldId}`);
+      const value = values[fieldId];
+      if (value !== null && !["string", "number", "boolean"].includes(typeof value) || typeof value === "number" && !Number.isFinite(value) || typeof value === "string" && value.length > 2000) throw new Error("YIDA_RULE_INPUT_INVALID");
+      return JSON.stringify(value);
+    });
+  }
+  return `{${appType}}@${expression}`;
+}

package/src/yida-runtime.mjs

@@ -0,0 +1,63 @@
+import { createHash } from "node:crypto";
+import { yidaRead, yidaLookupExpression, yidaApplicantConnector, yidaStatus } from "./yida-auth.mjs";
+import { describeYidaForm, modelYidaSchema, validateYidaForm } from "./yida-schema.mjs";
+import { compileYidaLookup } from "./yida-rules.mjs";
+
+export async function resolveYidaField(store, appType, formUuid, fieldId, values = {}, options = {}) {
+  validateYidaForm(appType, formUuid);
+  if (typeof fieldId !== "string" || !/^[A-Za-z][A-Za-z0-9_.-]{0,199}$/.test(fieldId) || !values || typeof values !== "object" || Array.isArray(values) || Object.keys(values).length > 100) throw new Error("YIDA_RULE_INPUT_INVALID");
+  const payload = await yidaRead(store, `/alibaba/web/${appType}/_view/query/formdesign/getFormSchema.json?${new URLSearchParams({ formUuid, schemaVersion: "V5" })}`, options);
+  const model = modelYidaSchema(payload, { appType, formUuid });
+  if (model.truncated || options.schemaHash && options.schemaHash !== model.schemaHash) throw new Error("YIDA_SCHEMA_CHANGED");
+  const kind = options.kind ?? "options";
+  const rules = model.runtime.rules.filter(rule => rule.fieldId === fieldId && rule.kind === kind);
+  if (rules.length !== 1) throw new Error("YIDA_RULE_UNSUPPORTED: select one configured options or linked-value rule");
+  const expression = compileYidaLookup(rules[0], values, appType);
+  const result = await yidaLookupExpression(store, appType, formUuid, expression, options);
+  const data = result.content ?? result.result;
+  if (!Array.isArray(data) || data.length > 1000) throw new Error("YIDA_LOOKUP_UNEXPECTED_RESPONSE");
+  return { fieldId, kind, values: data, evidence: { schemaHash: model.schemaHash, sourceFormUuid: rules[0].source.formUuid,
+    queryHash: `sha256:${createHash("sha256").update(expression).digest("hex")}`, verification: "api_readback", checkedAt: new Date().toISOString(),
+    // Related option requests have an explicit 100-item bound; no claim of completeness.
+    possiblyTruncated: rules[0].lookupMode === "relate" && data.length >= 100 } };
+}
+
+export async function resolveYidaApplicant(store, appType, formUuid, departmentId, options = {}) {
+  const status = await yidaStatus(store, options);
+  const candidates = status.profiles.filter(profile => !options.profile || profile.profile === options.profile);
+  if (candidates.length !== 1) throw new Error("YIDA_PROFILE_REQUIRED");
+  const principal = candidates[0];
+  const local = { ...options, profile: principal.profile };
+  const model = await describeYidaForm(store, appType, formUuid, local);
+  if (options.schemaHash && model.schemaHash !== options.schemaHash) throw new Error("YIDA_SCHEMA_CHANGED");
+  const hrConnector = model.runtime.connectors.find(source => source.name === "connector2");
+  const hrResponse = await yidaApplicantConnector(store, hrConnector, "self_hr", undefined, local);
+  return resolveYidaApplicantFromContext(store, model, principal, hrResponse, departmentId, local);
+}
+
+// Internal adapter entry: reuse a schema already checked against the live hash
+// and this operation's own HR response. Never accept these values over MCP.
+export async function resolveYidaApplicantFromContext(store, model, principal, hrResponse, departmentId, options = {}) {
+  const local = { ...options, profile: principal.profile };
+  if (options.schemaHash && model.schemaHash !== options.schemaHash) throw new Error("YIDA_SCHEMA_CHANGED");
+  const departmentConnector = model.runtime.connectors.find(source => source.name === "connector1");
+  const hr = hrResponse.content?.serviceReturnValue ?? hrResponse.content;
+  if (hr?.errcode !== 0 || hr.success !== true || hr.result?.length !== 1 || hr.result[0].userid !== principal.userId) throw new Error("YIDA_APPLICANT_LOOKUP_FAILED");
+  const fields = hr.result[0].field_data_list;
+  const field = (code, key = "value") => fields?.find(item => item.field_code === code)?.field_value_list?.[0]?.[key];
+  const ids = String(field("sys00-deptIds") ?? "").split("|");
+  const names = String(field("sys00-dept", "label") ?? "").split(",");
+  if (ids.length !== names.length || ids.some(id => !/^\d{1,20}$/.test(id))) throw new Error("YIDA_APPLICANT_DEPARTMENTS_INVALID");
+  const selectedId = departmentId ?? field("sys00-mainDeptId");
+  const index = ids.indexOf(selectedId);
+  if (index < 0) throw new Error("YIDA_APPLICANT_DEPARTMENT_FORBIDDEN");
+  const response = await yidaApplicantConnector(store, departmentConnector, "department", selectedId, local);
+  const dept = response.content?.serviceReturnValue ?? response.content;
+  const managers = dept?.result?.dept_manager_userid_list;
+  if (dept?.errcode !== 0 || !Array.isArray(managers) || !managers.length || managers.some(id => typeof id !== "string" || !/^[A-Za-z0-9_.@-]{1,200}$/.test(id))) throw new Error("YIDA_APPLICANT_MANAGER_UNRESOLVED");
+  return { userId: principal.userId, departmentId: selectedId, departmentName: names[index],
+    departments: ids.map((id, i) => ({ value: id, label: names[i] })),
+    // The page's fetchDeptManager selects the first returned manager.
+    managerIds: managers.slice(0, 1), workPlace: field("sys00-workPlace") ?? null, positionLevel: field("sys01-positionLevel", "label") ?? null,
+    evidence: { schemaHash: model.schemaHash, verification: "api_readback", checkedAt: new Date().toISOString() } };
+}

package/src/yida-schema.mjs

@@ -0,0 +1,111 @@
+// Schema conventions adapted from OpenYida (MIT). See THIRD_PARTY_NOTICES.md.
+import { createHash } from "node:crypto";
+import { yidaRead } from "./yida-auth.mjs";
+import { modelYidaRules } from "./yida-rules.mjs";
+
+export function validateYidaForm(appType, formUuid) {
+  if (!/^APP_[A-Za-z0-9_-]{1,200}$/.test(appType ?? "") || !/^FORM-[A-Za-z0-9_-]{1,200}$/.test(formUuid ?? "")) {
+    throw new Error("YIDA_FORM_INVALID: appType and formUuid must be exact YiDA identifiers");
+  }
+}
+
+function object(value) {
+  if (typeof value === "string") {
+    try { return JSON.parse(value); } catch { return null; }
+  }
+  return value && typeof value === "object" ? value : null;
+}
+
+function label(value) {
+  const parsed = object(value);
+  return String(parsed?.zh_CN ?? parsed?.zh_HK ?? parsed?.en_US ?? parsed?.text ?? (typeof value === "string" ? value : "")).slice(0, 1000);
+}
+
+function formReferences(value) {
+  return [...new Set((JSON.stringify(value) ?? "").match(/FORM-[A-Za-z0-9_-]+/g) ?? [])].sort();
+}
+
+function hasFormula(value) {
+  if (value === undefined || value === null || value === "") return false;
+  if (typeof value === "string") return Boolean(value.trim());
+  if (Array.isArray(value)) return value.length > 0;
+  if (typeof value !== "object") return Boolean(value);
+  if (["expression", "source", "value", "formula"].some(key => value[key] !== undefined && value[key] !== null && value[key] !== "")) return true;
+  if (Array.isArray(value.data) && value.data.length) return true;
+  return Boolean(value.event && typeof value.event === "object" && Object.values(value.event).some(events => Array.isArray(events) ? events.length > 0 : Boolean(events)));
+}
+
+export function modelYidaSchema(payload, { appType, formUuid }) {
+  const content = object(payload?.content ?? payload?.data ?? payload);
+  if (!Array.isArray(content?.pages)) throw new Error("YIDA_SCHEMA_UNAVAILABLE: the service did not return a readable schema; check form identity and design permissions");
+  const aliases = new Map();
+  for (const page of content.pages) {
+    for (const alias of page.componentAlias?.items ?? []) {
+      if (alias.fieldId && alias.alias) aliases.set(alias.fieldId, alias.alias);
+    }
+  }
+  const fields = [];
+  const dependencies = [];
+  const eventBindings = [];
+  let truncated = false;
+  function visit(node, parentFieldId = null, depth = 0) {
+    if (!node || typeof node !== "object") return;
+    if (depth > 100 || fields.length >= 2000) { truncated = true; return; }
+    const props = node.props ?? {};
+    let parent = parentFieldId;
+    if (typeof props.fieldId === "string" && /Field$/.test(node.componentName ?? "")) {
+      const source = Array.isArray(props.options) ? props.options :
+        [props.dataSource, props.dataSource?.options, props.dataSource?.data, props.dataSource?.list, props.dataSource?.values,
+          ...(props.defaultDataSource?.complexType === "custom" ? [props.defaultDataSource.options] : [])].find(Array.isArray);
+      const options = source?.slice(0, 100).map(item => {
+        if (item === null || typeof item !== "object") return { label: String(item), value: item };
+        const value = item.value ?? item.key ?? item.id;
+        return { label: label(item.label ?? item.text ?? item.name ?? item.title ?? value), ...(value !== undefined && ["string", "number", "boolean"].includes(typeof value) ? { value } : {}), ...(item.disabled === true ? { disabled: true } : {}) };
+      });
+      const validation = Array.isArray(props.validation) ? props.validation : [];
+      const requiredKnown = Object.hasOwn(props, "required") || validation.some(rule => rule?.type === "required" || rule?.required === true);
+      const formulaDetected = hasFormula(props.formula) || hasFormula(props.defaultDataSource?.formula) || hasFormula(props.complexValue?.formula);
+      const hasDataSource = Boolean(props.remoteDataSource || props.dataSourceLinkage || (props.dataSourceType && props.dataSourceType !== "custom") || (props.dataSource && !Array.isArray(props.dataSource) && !source));
+      const association = props.associationForm ?? props.associationFormConfig;
+      fields.push({
+        fieldId: props.fieldId, label: label(props.label), componentName: node.componentName,
+        alias: aliases.get(props.fieldId) ?? null, parentFieldId,
+        required: requiredKnown ? props.required === true || props.required === "true" || validation.some(rule => rule?.type === "required" || rule?.required === true) : null,
+        behavior: typeof props.behavior === "string" ? props.behavior : null,
+        hasDefault: [props.value, props.defaultValue, props.complexValue, props.defaultDataSource].some(value => value !== undefined && value !== null),
+        ...(options ? { options, optionCount: source.length, optionsTruncated: source.length > options.length } : {}),
+        hasFormula: formulaDetected, hasDynamicDataSource: hasDataSource
+      });
+      const refs = formReferences({ association, linkage: props.dataSourceLinkage, remote: props.remoteDataSource, source: props.dataSource, defaultSource: props.defaultDataSource, formula: props.formula, complexFormula: props.complexValue?.formula });
+      if (association || hasDataSource || formulaDetected || refs.length) {
+        dependencies.push({ fieldId: props.fieldId, kind: association ? "association" : hasDataSource ? "data_source" : "formula", formUuids: refs, resolution: "configuration_detected_runtime_not_verified" });
+      }
+      for (const [event, binding] of Object.entries(props)) {
+        if (!binding || typeof binding !== "object" || binding.type !== "JSExpression") continue;
+        const actions = Array.isArray(binding.events) ? binding.events.filter(item => item?.type === "actionRef").map(item => item.name ?? item.id).filter(value => typeof value === "string") : [];
+        if (actions.length) eventBindings.push({ fieldId: props.fieldId, event, actions });
+      }
+      parent = props.fieldId;
+    }
+    for (const child of Array.isArray(node.children) ? node.children : []) visit(child, parent, depth + 1);
+  }
+  for (const page of content.pages) for (const root of page.componentsTree ?? []) visit(root);
+  const runtime = modelYidaRules(content, appType);
+  truncated ||= runtime.truncated;
+  return {
+    kind: "yida_business_form", modelVersion: 2, appType, formUuid,
+    schemaHash: `sha256:${createHash("sha256").update(JSON.stringify(content)).digest("hex")}`,
+    fieldCount: fields.length, fields, dependencies, eventBindings, truncated,
+    verification: "schema_read_only", runtime,
+    unresolved: ["Dynamic options and effective employee permissions require runtime queries.", "Formula and event behavior is detected, not executed or fully reconstructed.", ...(truncated ? ["The field traversal limit was reached."] : [])],
+    // Default values and executable source are intentionally omitted from Agent output.
+    defaultsIncluded: false, executableSourceIncluded: false
+  };
+}
+
+export async function describeYidaForm(fargoStore, appType, formUuid, options = {}) {
+  validateYidaForm(appType, formUuid);
+  const query = new URLSearchParams({ formUuid, schemaVersion: "V5" });
+  const payload = await yidaRead(fargoStore, `/alibaba/web/${appType}/_view/query/formdesign/getFormSchema.json?${query}`, options);
+  return modelYidaSchema(payload, { appType, formUuid });
+}

package/src/yida-task.mjs

@@ -0,0 +1,38 @@
+import { createHash } from "node:crypto";
+import { resolveYidaOwner } from "./yida-auth.mjs";
+
+// Internal to one tool execution, never a caller-supplied identity or a global
+// login cache. Every reuse checks local credentials; every write refreshes online.
+export function createYidaTaskContext(store, options = {}) {
+  let fingerprint, identity, pending, closed = false;
+  const expiresAt = Date.now() + 5 * 60_000;
+  const hash = value => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+  const changed = () => { closed = true; throw new Error("YIDA_FARGO_ACCOUNT_CHANGED"); };
+  async function check() {
+    if (closed || Date.now() >= expiresAt) throw new Error("YIDA_TASK_EXPIRED");
+    const credential = await store.load();
+    const current = hash(credential ?? null);
+    if (fingerprint !== undefined && fingerprint !== current) changed();
+    fingerprint = current;
+  }
+  async function online() {
+    await check();
+    try {
+      const next = await resolveYidaOwner(store, options);
+      await check();
+      if (identity && hash(identity) !== hash(next)) changed();
+      identity = Object.freeze({ ...next });
+      return { ...identity };
+    } catch (error) { closed = true; throw error; }
+  }
+  async function owner() {
+    await check();
+    if (identity) return { ...identity };
+    if (!pending) pending = online().catch(error => { closed = true; throw error; });
+    return { ...await pending };
+  }
+  return {
+    options: { ...options, resolveYidaOwner: owner, revalidateYidaTaskOwner: online },
+    close() { closed = true; identity = undefined; pending = undefined; }
+  };
+}

package/src/yida-tools.mjs

@@ -0,0 +1,91 @@
+import { yidaStatus } from "./yida-auth.mjs";
+import { describeYidaForm } from "./yida-schema.mjs";
+import { getYidaBusinessBundle, listYidaBusinesses } from "./yida-business.mjs";
+import { resolveYidaField } from "./yida-runtime.mjs";
+import { cancelYidaRequest } from "./yida-cancellation.mjs";
+import { submitYidaExpense } from "./yida-expense.mjs";
+
+const profileProperty = { type: "string", pattern: "^[a-f0-9]{64}$", description: "Exact local authorization profile; required when multiple profiles exist." };
+const tools = [
+  {
+    name: "yida_connection_status", description: "Read local YiDA connection metadata for the current verified Fargo account. Does not validate upstream access or return credentials.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true }
+  },
+  {
+    name: "yida_describe_form", description: "Read a YiDA form schema using the current user's local authorization. Return fields, static options and detected dependency references. Dynamic options, formulas and effective permissions remain unverified. No business records are written.",
+    inputSchema: { type: "object", properties: { appType: { type: "string", pattern: "^APP_[A-Za-z0-9_-]{1,200}$" }, formUuid: { type: "string", pattern: "^FORM-[A-Za-z0-9_-]{1,200}$" }, profile: profileProperty }, required: ["appType", "formUuid"], additionalProperties: false },
+    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true }
+  },
+  {
+    name: "yida_resolve_field", description: "Resolve one form field's configured options or linked default with personal OAuth and the live form context. Uses only read-only lookup formulas recorded in that schema; never executes page JavaScript or accepts raw expressions.",
+    inputSchema: { type: "object", properties: { appType: { type: "string" }, formUuid: { type: "string" }, fieldId: { type: "string" }, kind: { type: "string", enum: ["options", "linked_value"] }, values: { type: "object", maxProperties: 100, additionalProperties: { type: ["string", "number", "boolean", "null"] } }, profile: profileProperty }, required: ["appType", "formUuid", "fieldId"], additionalProperties: false },
+    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true }
+  },
+  {
+    name: "yida_business_list", description: "List the publisher's selected employee-facing business entries matching the local YiDA enterprise, with Chinese names, groups and aliases. Match the user's request and fetch only the selected bundle; ask the user to choose if ambiguous. Background dictionaries and copied/test forms are omitted from discovery. Listing does not prove personal submission permission or availability of a submission adapter. Credentials remain local.",
+    inputSchema: { type: "object", properties: { profile: profileProperty }, additionalProperties: false },
+    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true }
+  },
+  {
+    name: "yida_business_bundle", description: "Fetch a matching version of the business Schema and Handbook from the LEGO App, validate and cache them together, then check the live YiDA schema locally. Reuse the returned revision and bundleHash throughout a workflow. schema_changed blocks preparation/submission. No submission tools are enabled; no offline authorization fallback.",
+    inputSchema: { type: "object", properties: {
+      businessId: { type: "string", pattern: "^[a-z][a-z0-9_]{0,79}$" },
+      revision: { type: "integer", minimum: 1 },
+      bundleHash: { type: "string", pattern: "^sha256:[a-f0-9]{64}$" }, profile: profileProperty
+    }, required: ["businessId"], additionalProperties: false },
+    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true }
+  },
+  {
+    name: "yida_cancel_request", description: "Preview or cancel the current member's own running YiDA workflow. Shared across process businesses whose Schema enables cancellation. Default dryRun=true reads only. To execute, reuse the preview's revision, bundleHash and previewHash with dryRun=false. Maps to YiDA termination, retains the record, and checks final state; never automatically retries a write. Permissions are enforced by YiDA.",
+    inputSchema: { type: "object", properties: {
+      businessId: { type: "string", pattern: "^[a-z][a-z0-9_]{0,79}$" },
+      processInstanceId: { type: "string", pattern: "^[A-Za-z0-9_-]{1,200}$" },
+      dryRun: { type: "boolean", default: true },
+      previewHash: { type: "string", pattern: "^sha256:[a-f0-9]{64}$" },
+      revision: { type: "integer", minimum: 1 },
+      bundleHash: { type: "string", pattern: "^sha256:[a-f0-9]{64}$" }, profile: profileProperty
+    }, required: ["businessId", "processInstanceId"], additionalProperties: false },
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true }
+  },
+  {
+    name: "yida_submit_expense", description: "Prepare or submit the current member's own non-project expense using the reviewed ordinary-expense form adapter. Reads personal HR bank details and live company, currency, accounting and routing lookups. Requires a previously uploaded local PDF receipt. Default dryRun=true returns confirmation.markdown with overall parameters and detail rows. Show it to the user and wait for explicit confirmation before setting userConfirmed=true with dryRun=false, the previewHash and exact business pin. Never infer confirmation from the initial request or tool output; changed previews require new user confirmation. Checks invoice/order duplicates and reads back the submitted record. No arbitrary form payloads, other originators, project claims or generic submission are supported. Never automatically retries a write.",
+    inputSchema: { type: "object", properties: {
+      amount: { type: "number", minimum: 0.01, maximum: 100000000 }, currency: { type: "string", pattern: "^[A-Z]{3}$" },
+      description: { type: "string", minLength: 1, maxLength: 1000 }, expenseCategory: { type: "string", minLength: 1, maxLength: 1000 },
+      accountingItem: { type: "string", minLength: 1, maxLength: 1000 }, costCompany: { type: "string", minLength: 1, maxLength: 1000 },
+      invoiceNumber: { type: "string", pattern: "^[0-9]{8,30}$" }, invoiceDate: { type: "string", pattern: "^\\d{4}-\\d{2}-\\d{2}$" },
+      userConfirmed: { type: "boolean", default: false, description: "Set true only after the human has explicitly confirmed this exact rendered preview. This is the caller attestation, not an authentication credential." },
+      paymentOrder: { type: "string", pattern: "^[A-Za-z0-9_-]{1,80}$" }, attachmentReceiptPath: { type: "string", description: "Absolute local path to the registered YiDA PDF upload receipt; never sent to the publisher App." },
+      profile: profileProperty, dryRun: { type: "boolean", default: true }, previewHash: { type: "string", pattern: "^sha256:[a-f0-9]{64}$" },
+      revision: { type: "integer", minimum: 1 }, bundleHash: { type: "string", pattern: "^sha256:[a-f0-9]{64}$" }
+    }, required: ["amount", "currency", "description", "expenseCategory", "accountingItem", "costCompany", "invoiceNumber", "invoiceDate", "paymentOrder", "attachmentReceiptPath"], additionalProperties: false },
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true }
+  }
+];
+
+export function localYidaTools() { return structuredClone(tools); }
+export function isLocalYidaTool(name) { return typeof name === "string" && name.startsWith("yida_"); }
+
+export async function callLocalYidaTool(store, name, args = {}, options = {}) {
+  const tool = tools.find(item => item.name === name);
+  if (!tool) throw new Error("Unknown local YiDA tool");
+  if (!args || typeof args !== "object" || Array.isArray(args) || Object.keys(args).some(key => !Object.hasOwn(tool.inputSchema.properties, key))) throw new Error("Invalid local YiDA tool arguments");
+  for (const required of tool.inputSchema.required ?? []) if (typeof args[required] !== tool.inputSchema.properties[required].type) throw new Error(`Missing YiDA argument: ${required}`);
+  if (args.profile !== undefined && (typeof args.profile !== "string" || !/^[a-f0-9]{64}$/.test(args.profile))) throw new Error("Invalid YiDA profile");
+  let value;
+  const localOptions = { ...options, profile: args.profile };
+  if (name === "yida_connection_status") value = await yidaStatus(store, options);
+  else if (name === "yida_describe_form") value = await describeYidaForm(store, args.appType, args.formUuid, localOptions);
+  else if (name === "yida_resolve_field") {
+    if (args.kind !== undefined && !["options", "linked_value"].includes(args.kind)) throw new Error("Invalid YiDA rule kind");
+    value = await resolveYidaField(store, args.appType, args.formUuid, args.fieldId, args.values ?? {}, { ...localOptions, kind: args.kind });
+  }
+  else if (name === "yida_business_list") value = await listYidaBusinesses(store, localOptions);
+  else if (name === "yida_submit_expense") value = await submitYidaExpense(store, args, localOptions);
+  else if (name === "yida_cancel_request") value = await cancelYidaRequest(store, args.businessId, args.processInstanceId, {
+    ...localOptions, dryRun: args.dryRun, previewHash: args.previewHash, revision: args.revision, bundleHash: args.bundleHash
+  });
+  else value = await getYidaBusinessBundle(store, args.businessId, { ...localOptions, revision: args.revision, bundleHash: args.bundleHash });
+  return { content: [{ type: "text", text: JSON.stringify(value) }], structuredContent: value, isError: false };
+}

package/src/yida-workflow-contract.mjs

@@ -0,0 +1,18 @@
+// A shared client capability declaration, not an upstream permission grant.
+export function workflowCancellationCapability() {
+  return { enabled: true, mode: "terminate", localTool: "yida_cancel_request", ownRequestsOnly: true,
+    allowedStates: ["RUNNING"], terminalStates: ["TERMINATED", "CANCELED"],
+    permission: "upstream_authorization_required_on_execute", verification: "active_termination_not_live_verified" };
+}
+
+export const workflowCancellationHandbook = `
+## 申请撤销（共用流程能力）
+
+本业务复用本地工具 yida_cancel_request，传入 businessId 与 processInstanceId。默认 dryRun=true，仅核实当前账号、企业、本人发起、表单与流程归属、当前状态和业务包版本，并返回 pin 与 previewHash。预览不代表宜搭已授予终止权限。
+
+用户明确要求撤销后，用预览返回的 revision、bundleHash、previewHash 与 dryRun=false 执行。只处理本人仍在 RUNNING 且未有审批结果的实例；执行前再次回读，定义、内容或状态变化须重新预览。宜搭负责最终权限校验。普通数据表不适用此功能。
+
+撤销对应宜搭 terminateInstance，保留申请记录，不删除数据，也不自动冲销已经发生的付款或其他业务动作。TERMINATED/CANCELED 返回 already_cancelled，不重复写入；已完成实例返回 not_cancellable。成功需通过 API 回读确认终止状态。该共用实现的活动流程终止尚未实单验证，不应宣称每个流程都已验证可撤销。
+
+写入使用每个账号、实例的持久化操作记录。超时或结果不确定时只做回读，不自动重发；保存的成功回执也不会重新发起终止。明确的授权拒绝或写入前失败允许修复原因后重新预览、显式执行。OAuth、申请数据和操作记录保留本地，不经业务包分发应用转发。
+`;

package/node_modules/@fargowealth/website-connector-runtime/README.md

@@ -1,15 +0,0 @@
-# Fargo Website Connector Runtime
-
-The shared, declarative Website Connector compiler and execution runtime used
-by both Fargo CLI local debugging and the Fargo Browser Gateway.
-
-Connector definitions contain data only. They cannot ship executable code.
-Callers provide browser storage at execution time; the runtime never persists
-cookies or localStorage.
-
-Runtime `1.1.0` adds declarative AWS Cognito token refresh. `secretSources`
-select refresh-only browser values, while `headerSources` remains the complete
-set of values allowed in business requests. The runtime can exchange an
-expiring session through Cognito's `GetTokensFromRefreshToken` API and returns a
-new in-memory storage state; the hosting BrowserConnectionSession Durable Object
-is responsible for encrypting and persisting that state before use.

package/node_modules/@fargowealth/website-connector-runtime/package.json

@@ -1,24 +0,0 @@
-{
-  "name": "@fargowealth/website-connector-runtime",
-  "version": "1.1.0",
-  "description": "Shared declarative Website Connector runtime for Fargo AI",
-  "type": "module",
-  "exports": {
-    ".": {
-      "types": "./src/index.d.mts",
-      "import": "./src/index.mjs"
-    }
-  },
-  "files": [
-    "src",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=20.19.0"
-  },
-  "private": true,
-  "scripts": {
-    "test": "node --test test/*.test.mjs"
-  },
-  "license": "UNLICENSED"
-}