@namzu/sdk 27.1.0 → 28.0.0

package/dist/vault/CredentialProvider.js

@@ -0,0 +1,64 @@
+import { isCredentialEnvKey } from '../constants/credential-env-keys.js';
+import { NamzuError } from '../types/errors/index.js';
+/** A write attempted against a provider that cannot perform one. */
+export class ReadOnlyCredentialProviderError extends NamzuError {
+    constructor(ref, source, alternative) {
+        super({
+            code: 'invalid_config',
+            message: `${source} cannot store credentials: "${ref}" is read from the process environment, which this process does not own. ${alternative}`,
+            details: { ref, source },
+            retryable: false,
+        });
+        this.name = 'ReadOnlyCredentialProviderError';
+    }
+}
+/**
+ * Credentials from the process environment.
+ *
+ * Read-only, and it says so rather than accepting a write and dropping it.
+ * `process.env` is inherited from whoever started this process; a `set` here
+ * would change one map in one process and vanish with it, while every
+ * caller who asked would be told it worked. That is the quiet degradation
+ * this repo has a rule about, and for a credential the failure surfaces
+ * later as an authentication error pointing nowhere.
+ */
+export class EnvCredentialProvider {
+    static source = 'env';
+    env;
+    anyKey;
+    constructor(options = {}) {
+        this.env = options.env ?? process.env;
+        this.anyKey = options.anyKey ?? false;
+    }
+    answers(ref) {
+        return this.anyKey || isCredentialEnvKey(ref);
+    }
+    async resolve(ref) {
+        if (!this.answers(ref))
+            return undefined;
+        const value = this.env[ref];
+        // An empty string is not a credential. A variable exported as `FOO=`
+        // is the shape a shell script produces when a lookup failed, and
+        // treating it as present sends a caller off to authenticate with
+        // nothing.
+        return value ? { value, source: EnvCredentialProvider.source } : undefined;
+    }
+    async describe(ref) {
+        const found = await this.resolve(ref);
+        return {
+            configured: found !== undefined,
+            ...(found ? { source: found.source } : {}),
+            writable: false,
+        };
+    }
+    // Takes the value it will not store, so the signature reads as the
+    // interface's and a caller does not have to discover the refusal by
+    // getting an arity error instead of the named one.
+    async set(ref, _value) {
+        throw new ReadOnlyCredentialProviderError(ref, EnvCredentialProvider.source, 'Set it in the environment this process is started from, or supply a writable CredentialProvider.');
+    }
+    async unset(ref) {
+        throw new ReadOnlyCredentialProviderError(ref, EnvCredentialProvider.source, 'Unset it in the environment this process is started from, or supply a writable CredentialProvider.');
+    }
+}
+//# sourceMappingURL=CredentialProvider.js.map

package/dist/vault/CredentialProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CredentialProvider.js","sourceRoot":"","sources":["../../src/vault/CredentialProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAA;AACxE,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAwDrD,oEAAoE;AACpE,MAAM,OAAO,+BAAgC,SAAQ,UAAU;IAC9D,YAAY,GAAkB,EAAE,MAAc,EAAE,WAAmB;QAClE,KAAK,CAAC;YACL,IAAI,EAAE,gBAAgB;YACtB,OAAO,EAAE,GAAG,MAAM,+BAA+B,GAAG,4EAA4E,WAAW,EAAE;YAC7I,OAAO,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE;YACxB,SAAS,EAAE,KAAK;SAChB,CAAC,CAAA;QACF,IAAI,CAAC,IAAI,GAAG,iCAAiC,CAAA;IAC9C,CAAC;CACD;AAgBD;;;;;;;;;GASG;AACH,MAAM,OAAO,qBAAqB;IACjC,MAAM,CAAU,MAAM,GAAG,KAAK,CAAA;IAEb,GAAG,CAAmB;IACtB,MAAM,CAAS;IAEhC,YAAY,UAAwC,EAAE;QACrD,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAA;QACrC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,KAAK,CAAA;IACtC,CAAC;IAEO,OAAO,CAAC,GAAkB;QACjC,OAAO,IAAI,CAAC,MAAM,IAAI,kBAAkB,CAAC,GAAG,CAAC,CAAA;IAC9C,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,GAAkB;QAC/B,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC;YAAE,OAAO,SAAS,CAAA;QACxC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAC3B,qEAAqE;QACrE,iEAAiE;QACjE,iEAAiE;QACjE,WAAW;QACX,OAAO,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,qBAAqB,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CAAA;IAC3E,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,GAAkB;QAChC,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;QACrC,OAAO;YACN,UAAU,EAAE,KAAK,KAAK,SAAS;YAC/B,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1C,QAAQ,EAAE,KAAK;SACf,CAAA;IACF,CAAC;IAED,mEAAmE;IACnE,oEAAoE;IACpE,mDAAmD;IACnD,KAAK,CAAC,GAAG,CAAC,GAAkB,EAAE,MAAc;QAC3C,MAAM,IAAI,+BAA+B,CACxC,GAAG,EACH,qBAAqB,CAAC,MAAM,EAC5B,kGAAkG,CAClG,CAAA;IACF,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,GAAkB;QAC7B,MAAM,IAAI,+BAA+B,CACxC,GAAG,EACH,qBAAqB,CAAC,MAAM,EAC5B,oGAAoG,CACpG,CAAA;IACF,CAAC"}

package/dist/vault/InMemoryCredentialVault.d.ts

@@ -1,10 +1,11 @@
 import type { AuthConfig, CredentialRef, CredentialVault } from '../types/connector/index.js';
 import type { ConnectorId, CredentialId, TenantId } from '../types/ids/index.js';
+import { type Logger } from '../utils/logger.js';
 export declare class InMemoryCredentialVault implements CredentialVault {
     private refs;
     private secrets;
     private log;
-    constructor();
+    constructor(log?: Logger);
     store(tenantId: TenantId, connectorId: ConnectorId, label: string, auth: AuthConfig): Promise<CredentialRef>;
     retrieve(credentialId: CredentialId): Promise<AuthConfig | undefined>;
     revoke(credentialId: CredentialId): Promise<boolean>;

package/dist/vault/InMemoryCredentialVault.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"InMemoryCredentialVault.d.ts","sourceRoot":"","sources":["../../src/vault/InMemoryCredentialVault.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAA;AAC7F,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AAIhF,qBAAa,uBAAwB,YAAW,eAAe;IAC9D,OAAO,CAAC,IAAI,CAA8C;IAC1D,OAAO,CAAC,OAAO,CAA2C;IAC1D,OAAO,CAAC,GAAG,CAAQ;;IAMb,KAAK,CACV,QAAQ,EAAE,QAAQ,EAClB,WAAW,EAAE,WAAW,EACxB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,UAAU,GACd,OAAO,CAAC,aAAa,CAAC;IAiBnB,QAAQ,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAIrE,MAAM,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC;IAUpD,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,WAAW,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;CASnF"}
+{"version":3,"file":"InMemoryCredentialVault.d.ts","sourceRoot":"","sources":["../../src/vault/InMemoryCredentialVault.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAA;AAC7F,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AAIhF,OAAO,EAAE,KAAK,MAAM,EAAiB,MAAM,oBAAoB,CAAA;AAE/D,qBAAa,uBAAwB,YAAW,eAAe;IAC9D,OAAO,CAAC,IAAI,CAA8C;IAC1D,OAAO,CAAC,OAAO,CAA2C;IAC1D,OAAO,CAAC,GAAG,CAAQ;gBAEP,GAAG,CAAC,EAAE,MAAM;IAIlB,KAAK,CACV,QAAQ,EAAE,QAAQ,EAClB,WAAW,EAAE,WAAW,EACxB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,UAAU,GACd,OAAO,CAAC,aAAa,CAAC;IAsBnB,QAAQ,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAIrE,MAAM,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC;IAapD,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,WAAW,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;CASnF"}

package/dist/vault/InMemoryCredentialVault.js

@@ -1,11 +1,13 @@
+import { NAMZU } from '../constants/telemetry/index.js';
 import { generateCredentialId } from '../utils/id.js';
-import { getRootLogger } from '../utils/logger.js';
+import { SCOPE_ATTRIBUTE } from '../utils/log/types.js';
+import { resolveLogger } from '../utils/logger.js';
 export class InMemoryCredentialVault {
     refs = new Map();
     secrets = new Map();
     log;
-    constructor() {
-        this.log = getRootLogger().child({ component: 'InMemoryCredentialVault' });
+    constructor(log) {
+        this.log = resolveLogger(log).child({ [SCOPE_ATTRIBUTE]: 'vault' });
     }
     async store(tenantId, connectorId, label, auth) {
         const id = generateCredentialId();
@@ -19,7 +21,12 @@ export class InMemoryCredentialVault {
         };
         this.refs.set(id, ref);
         this.secrets.set(id, auth);
-        this.log.info(`Credential stored: ${id} (${label}) for tenant ${tenantId}`);
+        const storedAttributes = {
+            [NAMZU.CREDENTIAL_ID]: id,
+            [NAMZU.CREDENTIAL_LABEL]: label,
+            [NAMZU.TENANT_ID]: tenantId,
+        };
+        this.log.info('Credential stored', storedAttributes);
         return ref;
     }
     async retrieve(credentialId) {
@@ -30,7 +37,10 @@ export class InMemoryCredentialVault {
         this.refs.delete(credentialId);
         this.secrets.delete(credentialId);
         if (existed) {
-            this.log.info(`Credential revoked: ${credentialId}`);
+            const revokedAttributes = {
+                [NAMZU.CREDENTIAL_ID]: credentialId,
+            };
+            this.log.info('Credential revoked', revokedAttributes);
         }
         return existed;
     }

package/dist/vault/InMemoryCredentialVault.js.map

@@ -1 +1 @@
-{"version":3,"file":"InMemoryCredentialVault.js","sourceRoot":"","sources":["../../src/vault/InMemoryCredentialVault.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AACrD,OAAO,EAAe,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAE/D,MAAM,OAAO,uBAAuB;IAC3B,IAAI,GAAqC,IAAI,GAAG,EAAE,CAAA;IAClD,OAAO,GAAkC,IAAI,GAAG,EAAE,CAAA;IAClD,GAAG,CAAQ;IAEnB;QACC,IAAI,CAAC,GAAG,GAAG,aAAa,EAAE,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,yBAAyB,EAAE,CAAC,CAAA;IAC3E,CAAC;IAED,KAAK,CAAC,KAAK,CACV,QAAkB,EAClB,WAAwB,EACxB,KAAa,EACb,IAAgB;QAEhB,MAAM,EAAE,GAAG,oBAAoB,EAAE,CAAA;QACjC,MAAM,GAAG,GAAkB;YAC1B,EAAE;YACF,WAAW;YACX,QAAQ;YACR,KAAK;YACL,QAAQ,EAAE,IAAI,CAAC,IAAI;YACnB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;SACrB,CAAA;QAED,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAA;QACtB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,CAAA;QAC1B,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,sBAAsB,EAAE,KAAK,KAAK,gBAAgB,QAAQ,EAAE,CAAC,CAAA;QAC3E,OAAO,GAAG,CAAA;IACX,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,YAA0B;QACxC,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAA;IACtC,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,YAA0B;QACtC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,CAAA;QAC3C,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,CAAA;QAC9B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,CAAA;QACjC,IAAI,OAAO,EAAE,CAAC;YACb,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,uBAAuB,YAAY,EAAE,CAAC,CAAA;QACrD,CAAC;QACD,OAAO,OAAO,CAAA;IACf,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,QAAkB,EAAE,WAAyB;QACvD,MAAM,OAAO,GAAoB,EAAE,CAAA;QACnC,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;YACtC,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ;gBAAE,SAAQ;YACvC,IAAI,WAAW,IAAI,GAAG,CAAC,WAAW,KAAK,WAAW;gBAAE,SAAQ;YAC5D,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QAClB,CAAC;QACD,OAAO,OAAO,CAAA;IACf,CAAC;CACD"}
+{"version":3,"file":"InMemoryCredentialVault.js","sourceRoot":"","sources":["../../src/vault/InMemoryCredentialVault.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,iCAAiC,CAAA;AAGvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AAErD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,EAAe,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAE/D,MAAM,OAAO,uBAAuB;IAC3B,IAAI,GAAqC,IAAI,GAAG,EAAE,CAAA;IAClD,OAAO,GAAkC,IAAI,GAAG,EAAE,CAAA;IAClD,GAAG,CAAQ;IAEnB,YAAY,GAAY;QACvB,IAAI,CAAC,GAAG,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,eAAe,CAAC,EAAE,OAAO,EAAE,CAAC,CAAA;IACpE,CAAC;IAED,KAAK,CAAC,KAAK,CACV,QAAkB,EAClB,WAAwB,EACxB,KAAa,EACb,IAAgB;QAEhB,MAAM,EAAE,GAAG,oBAAoB,EAAE,CAAA;QACjC,MAAM,GAAG,GAAkB;YAC1B,EAAE;YACF,WAAW;YACX,QAAQ;YACR,KAAK;YACL,QAAQ,EAAE,IAAI,CAAC,IAAI;YACnB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;SACrB,CAAA;QAED,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAA;QACtB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,CAAA;QAC1B,MAAM,gBAAgB,GAAkB;YACvC,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,EAAE;YACzB,CAAC,KAAK,CAAC,gBAAgB,CAAC,EAAE,KAAK;YAC/B,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,QAAQ;SAC3B,CAAA;QACD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,mBAAmB,EAAE,gBAAgB,CAAC,CAAA;QACpD,OAAO,GAAG,CAAA;IACX,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,YAA0B;QACxC,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAA;IACtC,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,YAA0B;QACtC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,CAAA;QAC3C,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,CAAA;QAC9B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,CAAA;QACjC,IAAI,OAAO,EAAE,CAAC;YACb,MAAM,iBAAiB,GAAkB;gBACxC,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,YAAY;aACnC,CAAA;YACD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,oBAAoB,EAAE,iBAAiB,CAAC,CAAA;QACvD,CAAC;QACD,OAAO,OAAO,CAAA;IACf,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,QAAkB,EAAE,WAAyB;QACvD,MAAM,OAAO,GAAoB,EAAE,CAAA;QACnC,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;YACtC,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ;gBAAE,SAAQ;YACvC,IAAI,WAAW,IAAI,GAAG,CAAC,WAAW,KAAK,WAAW;gBAAE,SAAQ;YAC5D,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QAClB,CAAC;QACD,OAAO,OAAO,CAAA;IACf,CAAC;CACD"}

package/dist/vault/index.d.ts

@@ -1,2 +1,5 @@
 export { InMemoryCredentialVault } from './InMemoryCredentialVault.js';
+export { wrapCredentialProviderWithProbes } from './instrumentation.js';
+export { EnvCredentialProvider, ReadOnlyCredentialProviderError, } from './CredentialProvider.js';
+export type { CredentialDescription, CredentialProvider, CredentialRef, EnvCredentialProviderOptions, ResolvedCredential, } from './CredentialProvider.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/vault/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/vault/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/vault/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAA;AAKtE,OAAO,EAAE,gCAAgC,EAAE,MAAM,sBAAsB,CAAA;AACvE,OAAO,EACN,qBAAqB,EACrB,+BAA+B,GAC/B,MAAM,yBAAyB,CAAA;AAChC,YAAY,EACX,qBAAqB,EACrB,kBAAkB,EAClB,aAAa,EACb,4BAA4B,EAC5B,kBAAkB,GAClB,MAAM,yBAAyB,CAAA"}

package/dist/vault/index.js

@@ -1,2 +1,7 @@
 export { InMemoryCredentialVault } from './InMemoryCredentialVault.js';
+// Where a credential comes from, as a seam a host can implement — parallel
+// to the connector-scoped `CredentialVault`, which answers a different
+// question and holds a whole `AuthConfig` per connector.
+export { wrapCredentialProviderWithProbes } from './instrumentation.js';
+export { EnvCredentialProvider, ReadOnlyCredentialProviderError, } from './CredentialProvider.js';
 //# sourceMappingURL=index.js.map

package/dist/vault/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/vault/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/vault/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAA;AAEtE,2EAA2E;AAC3E,uEAAuE;AACvE,yDAAyD;AACzD,OAAO,EAAE,gCAAgC,EAAE,MAAM,sBAAsB,CAAA;AACvE,OAAO,EACN,qBAAqB,EACrB,+BAA+B,GAC/B,MAAM,yBAAyB,CAAA"}

package/dist/vault/instrumentation.d.ts

@@ -1,11 +1,27 @@
-import { type ProbeRegistry } from '../probe/registry.js';
+import type { ProbeObservation } from '../probe/registry.js';
 import type { CredentialVault } from '../types/connector/index.js';
 import type { RunId, TenantId } from '../types/ids/index.js';
+import type { CredentialProvider } from './CredentialProvider.js';
 export interface VaultInstrumentationOptions {
-    readonly probes?: ProbeRegistry;
+    /** Observation only — a vault wrapper records, it never refuses. */
+    readonly probes?: ProbeObservation;
     readonly runId?: RunId;
     readonly vaultId?: string;
     readonly tenantId?: TenantId;
 }
 export declare function wrapVaultWithProbes(vault: CredentialVault, opts?: VaultInstrumentationOptions): CredentialVault;
+/**
+ * Wrap a {@link CredentialProvider} so a change is observable.
+ *
+ * Through the SAME probe registry `vault_lookup` already uses. A second bus
+ * would mean a subscriber that saw lookups and not rotations, or the other
+ * way round, depending on which one it happened to find.
+ *
+ * `rotated` rather than `set` when a value was already there, and the
+ * distinction is the one a reader actually wants: a first write is
+ * configuration, a replacement is a credential turning over.
+ */
+export declare function wrapCredentialProviderWithProbes(provider: CredentialProvider, opts?: VaultInstrumentationOptions & {
+    readonly source?: string;
+}): CredentialProvider;
 //# sourceMappingURL=instrumentation.d.ts.map

package/dist/vault/instrumentation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instrumentation.d.ts","sourceRoot":"","sources":["../../src/vault/instrumentation.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,aAAa,EAAiC,MAAM,sBAAsB,CAAA;AACxF,OAAO,KAAK,EAA6B,eAAe,EAAE,MAAM,6BAA6B,CAAA;AAC7F,OAAO,KAAK,EAA6B,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AAEvF,MAAM,WAAW,2BAA2B;IAC3C,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAA;IAC/B,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAA;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAA;CAC5B;AAED,wBAAgB,mBAAmB,CAClC,KAAK,EAAE,eAAe,EACtB,IAAI,GAAE,2BAAgC,GACpC,eAAe,CAwCjB"}
+{"version":3,"file":"instrumentation.d.ts","sourceRoot":"","sources":["../../src/vault/instrumentation.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAC5D,OAAO,KAAK,EAA6B,eAAe,EAAE,MAAM,6BAA6B,CAAA;AAC7F,OAAO,KAAK,EAA6B,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AACvF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAEjE,MAAM,WAAW,2BAA2B;IAC3C,oEAAoE;IACpE,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAA;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAA;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAA;CAC5B;AAED,wBAAgB,mBAAmB,CAClC,KAAK,EAAE,eAAe,EACtB,IAAI,GAAE,2BAAgC,GACpC,eAAe,CAwCjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gCAAgC,CAC/C,QAAQ,EAAE,kBAAkB,EAC5B,IAAI,GAAE,2BAA2B,GAAG;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GACnE,kBAAkB,CA0CpB"}

package/dist/vault/instrumentation.js

@@ -29,4 +29,51 @@ export function wrapVaultWithProbes(vault, opts = {}) {
         },
     };
 }
+/**
+ * Wrap a {@link CredentialProvider} so a change is observable.
+ *
+ * Through the SAME probe registry `vault_lookup` already uses. A second bus
+ * would mean a subscriber that saw lookups and not rotations, or the other
+ * way round, depending on which one it happened to find.
+ *
+ * `rotated` rather than `set` when a value was already there, and the
+ * distinction is the one a reader actually wants: a first write is
+ * configuration, a replacement is a credential turning over.
+ */
+export function wrapCredentialProviderWithProbes(provider, opts = {}) {
+    const probes = opts.probes ?? defaultProbeRegistry;
+    const source = opts.source ?? provider.constructor.name;
+    const announce = (kind, ref) => {
+        probes.dispatch({
+            type: 'vault_credential_changed',
+            kind,
+            source,
+            // The NAME, never the value. A change event exists to be logged,
+            // forwarded and retained, which is exactly what a credential
+            // must not be.
+            ref,
+            ...(opts.tenantId ? { tenantId: opts.tenantId } : {}),
+            ...(opts.runId ? { runId: opts.runId } : {}),
+        }, buildProbeContext());
+    };
+    return {
+        resolve: (ref) => provider.resolve(ref),
+        describe: (ref) => provider.describe(ref),
+        async set(ref, value) {
+            // Asked BEFORE the write, because afterwards every credential looks
+            // like it was always there — and "configured for the first time"
+            // and "rotated" are the two facts this event exists to separate.
+            const before = await provider.describe(ref);
+            await provider.set(ref, value);
+            // Emitted only on success. A write that threw changed nothing, and
+            // an event for it would have a reader chasing a rotation that
+            // never happened.
+            announce(before.configured ? 'rotated' : 'set', ref);
+        },
+        async unset(ref) {
+            await provider.unset(ref);
+            announce('unset', ref);
+        },
+    };
+}
 //# sourceMappingURL=instrumentation.js.map

package/dist/vault/instrumentation.js.map

@@ -1 +1 @@
-{"version":3,"file":"instrumentation.js","sourceRoot":"","sources":["../../src/vault/instrumentation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,EAAsB,KAAK,IAAI,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAWxF,MAAM,UAAU,mBAAmB,CAClC,KAAsB,EACtB,OAAoC,EAAE;IAEtC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,oBAAoB,CAAA;IAClD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAA;IACxB,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,KAAK,CAAC,WAAW,CAAC,IAAI,CAAA;IACtD,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,CAAA;IAElC,OAAO;QACN,KAAK,CACJ,QAAkB,EAClB,WAAwB,EACxB,KAAa,EACb,IAAgB;YAEhB,OAAO,KAAK,CAAC,KAAK,CAAC,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,IAAI,CAAC,CAAA;QACvD,CAAC;QAED,KAAK,CAAC,QAAQ,CAAC,YAA0B;YACxC,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAA;YACjD,MAAM,CAAC,QAAQ,CACd;gBACC,IAAI,EAAE,cAAc;gBACpB,OAAO;gBACP,YAAY;gBACZ,QAAQ,EAAE,YAAY;gBACtB,KAAK,EAAE,MAAM,KAAK,SAAS;gBAC3B,KAAK;aACL,EACD,iBAAiB,CAAC,EAAE,KAAK,EAAE,CAAC,CAC5B,CAAA;YACD,OAAO,MAAM,CAAA;QACd,CAAC;QAED,MAAM,CAAC,YAA0B;YAChC,OAAO,KAAK,CAAC,MAAM,CAAC,YAAY,CAAC,CAAA;QAClC,CAAC;QAED,IAAI,CAAC,QAAkB,EAAE,WAAyB;YACjD,OAAO,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAA;QACzC,CAAC;KACD,CAAA;AACF,CAAC"}
+{"version":3,"file":"instrumentation.js","sourceRoot":"","sources":["../../src/vault/instrumentation.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namzu/sdk",
-  "version": "27.1.0",
+  "version": "28.0.0",
   "description": "Open-source AI agent SDK with a built-in runtime. Nothing between you and your agents.",
   "license": "FSL-1.1-MIT",
   "type": "module",
@@ -21,9 +21,9 @@
       "default": "./dist/index.js"
     },
     "./testing": {
-      "types": "./dist/store/run/conformance.d.ts",
-      "import": "./dist/store/run/conformance.js",
-      "default": "./dist/store/run/conformance.js"
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js",
+      "default": "./dist/testing.js"
     }
   },
   "files": [

package/src/advisory/executor.ts

@@ -1,15 +1,17 @@
 import { CHARS_PER_TOKEN, ZERO_COST } from '../constants/limits.js'
 import { assembleSystemPrompt } from '../persona/assembler.js'
 import { resolveModelPricing } from '../pricing/index.js'
-import { collect } from '../provider/collect.js'
+import { collectChatCompletion } from '../provider/collect-chat-completion.js'
+import { SCOPE_ATTRIBUTE } from '../utils/log/types.js'
 
+import { GENAI } from '../constants/telemetry/index.js'
 import type { AdvisorDefinition, AdvisoryBudget } from '../types/advisory/config.js'
 import type { AdvisoryRequest, AdvisoryResult } from '../types/advisory/result.js'
 import type { CostInfo, TokenUsage } from '../types/common/index.js'
 import { type Message, createSystemMessage, createUserMessage } from '../types/message/index.js'
 import type { LLMToolSchema } from '../types/tool/index.js'
 import { accumulateUnpricedCost, calculateCost } from '../utils/cost.js'
-import { type Logger, getRootLogger } from '../utils/logger.js'
+import { type Logger, resolveLogger } from '../utils/logger.js'
 import { ADVISORY_RESPONSE_CONTRACT, parseAdvisoryResponse } from './parse.js'
 
 /**
@@ -44,7 +46,7 @@ export class AdvisoryExecutor {
 	private readonly budget: AdvisoryBudget | undefined
 
 	constructor(logger?: Logger, budget?: AdvisoryBudget) {
-		this.logger = (logger ?? getRootLogger()).child({ component: 'AdvisoryExecutor' })
+		this.logger = resolveLogger(logger).child({ [SCOPE_ATTRIBUTE]: 'advisory/executor' })
 		this.budget = budget
 	}
 
@@ -77,13 +79,13 @@ export class AdvisoryExecutor {
 		]
 
 		this.logger.debug('advisory call starting', {
-			advisorId: advisor.id,
-			model: advisor.model,
-			messageCount: messages.length,
-			urgency: request.urgency,
+			'namzu.advisory.id': advisor.id,
+			[GENAI.REQUEST_MODEL]: advisor.model,
+			'namzu.advisory.message_count': messages.length,
+			'namzu.advisory.urgency': request.urgency,
 		})
 
-		const response = await collect(
+		const response = await collectChatCompletion(
 			advisor.provider.chatStream({
 				model: advisor.model,
 				messages,
@@ -100,10 +102,10 @@ export class AdvisoryExecutor {
 		const cost = this.computeCost(advisor, response.usage)
 
 		this.logger.info('advisory call completed', {
-			advisorId: advisor.id,
-			model: advisor.model,
-			durationMs,
-			totalTokens: response.usage.totalTokens,
+			'namzu.advisory.id': advisor.id,
+			[GENAI.REQUEST_MODEL]: advisor.model,
+			'namzu.duration_ms': durationMs,
+			'namzu.usage.total_tokens': response.usage.totalTokens,
 		})
 
 		return {

package/src/advisory/registry.ts

@@ -1,7 +1,7 @@
-import { Registry } from '../registry/Registry.js'
+import { BaseRegistry } from '../registry/BaseRegistry.js'
 import type { AdvisorDefinition } from '../types/advisory/index.js'
 
-export class AdvisorRegistry extends Registry<AdvisorDefinition> {
+export class AdvisorRegistry extends BaseRegistry<AdvisorDefinition> {
 	private readonly defaultId: string | undefined
 
 	constructor(advisors: AdvisorDefinition[], defaultId?: string) {

package/src/agents/AGENTS.md

@@ -0,0 +1,91 @@
+# AGENTS.md — `packages/sdk/src/agents/`
+
+Nested instructions for work inside this directory. The repository root
+`AGENTS.md` establishes that a nested file overrides it here; everything it
+says that this file does not contradict still applies.
+
+This file exists because a position kept being attributed to it while it did
+not exist. An audit cited `packages/sdk/src/agents/AGENTS.md` as carrying the
+stance on model-authored control flow; `find . -name AGENTS.md` returned the
+repository root and nothing else. The stance was being inferred from the shape
+of the code and re-derived by each reader, which is how a decision turns into
+folklore.
+
+## What lives here
+
+Orchestration primitives, all **developer-authored**.
+
+- **`PipelineAgent.ts`** — a fixed step list the developer wrote. The steps
+  run with **zero model turns between them**: the control flow is code, and
+  the model is called only where a step calls it.
+- **`SupervisorAgent.ts`** — delegation driven by the model emitting
+  `create_task` tool calls. Note what this already does: **N `create_task`
+  blocks in one assistant turn run concurrently**, so fan-out costs one turn
+  for N children, not N turns. The mechanism, checked rather than assumed:
+  `tools/coordinator/index.ts` declares `create_task` with
+  `concurrencySafe: true`, and `runtime/query/executor.ts` collects every
+  concurrency-safe call of a batch into one `Promise.all`.
+  Do not read `SupervisorAgent`'s own "one run at a time per instance"
+  comment as contradicting this — that is about two overlapping RUNS sharing
+  one instance's abort controller, a different question from parallelism
+  inside a single turn.
+- **`AbstractAgent.ts`** — the base every agent extends; capabilities are
+  declared, not inferred.
+- **`runAgent.ts`** — the entry a host calls.
+
+## The decided position: control flow is authored by a developer
+
+A model may choose *what* to do — which tool, which delegate, in what order
+within a turn. It does not author the *program* that runs those choices.
+
+The proposal this rules on is a model-emitted orchestration SCRIPT —
+`agent()`, `parallel()`, `pipeline()` as globals — executed in an isolate, so
+that logic between steps costs no model turns. It is refused, and the reason
+is the trust boundary rather than the feature's value.
+
+**The argument.** `bash` from a model is mediated by `packages/sandbox`
+because code from a model is untrusted input. A model-authored script is the
+same input through a different door, and a strictly more powerful one: it can
+call back into the agent surface, spawn delegates and spend budget, which a
+shell command reaching only the filesystem cannot. Running it in-process would
+leave the kernel's one clearly-drawn confinement boundary covering the weaker
+case and not the stronger. So an isolate is mandatory rather than an
+optimisation — and once it is mandatory, the capability costs a **second
+mediated execution surface** to secure, audit, version and keep in step with
+the first.
+
+**What it would buy, measured honestly.** Model turns spent on orchestration
+between steps. That is real, and most of it is already available: `PipelineAgent`
+spends none, and `SupervisorAgent`'s concurrent `create_task` fan-out spends
+one turn for N children. The remaining gap is orchestration a developer did
+not anticipate and a model invents at runtime — which is also the case where a
+wrong program is hardest to review before it runs.
+
+## The bar a reopen has to clear
+
+Not "someone wants it". Specifically:
+
+1. **A decided trust model**, in writing, before any code: mediated by
+   `packages/sandbox` like `bash`, or not at all. "Decide later" is the
+   answer this refusal rejects.
+2. **A second execution surface worth its own maintenance** — its own
+   confinement, its own audit records, its own version story. If the answer
+   is "reuse the sandbox", show how a script that calls `agent()` is confined
+   by a boundary designed for a subprocess.
+3. **A measured gap**, against `PipelineAgent` and concurrent `create_task`
+   rather than against a single sequential agent. The comparison the original
+   proposal made was to the wrong baseline.
+
+Recorded in `ses_020`'s decision log as D5. If the owner reverses it, replace
+this section rather than adding to it — two stances in one file is how the
+first one got lost.
+
+## Working here
+
+- An agent's capabilities are **declared** on its metadata and honoured by the
+  runtime. Adding a capability means declaring it and driving it in the same
+  change; a declared capability nothing reads is the
+  `declared-but-undriven` defect this repo has a convention page about.
+- `AbstractAgent` takes an injected `Logger`. Do not reach for
+  `getRootLogger()` here — see `docs/conventions/` and the log-standard gate,
+  which counts every call site.

package/src/agents/AbstractAgent.ts

@@ -1,4 +1,5 @@
 import { EMPTY_TOKEN_USAGE } from '../constants/limits.js'
+import { GENAI, NAMZU } from '../constants/telemetry/index.js'
 import type {
 	Agent,
 	AgentCapabilities,
@@ -10,11 +11,13 @@ import type {
 } from '../types/agent/index.js'
 import type { AgentManagerContract } from '../types/agent/manager.js'
 import type { RunId } from '../types/ids/index.js'
+import { type CancelCause, RunCancelled } from '../types/run/cancel-cause.js'
 import type { RunEvent, RunEventListener } from '../types/run/index.js'
 import { ZERO_COST } from '../utils/cost.js'
 import { toErrorMessage } from '../utils/error.js'
 import { generateRunId } from '../utils/id.js'
-import { type Logger, getRootLogger } from '../utils/logger.js'
+import { SCOPE_ATTRIBUTE } from '../utils/log/types.js'
+import { type Logger, resolveLogger } from '../utils/logger.js'
 import { InvocationLock } from './lock.js'
 
 export abstract class AbstractAgent<
@@ -25,6 +28,14 @@ export abstract class AbstractAgent<
 	abstract readonly type: AgentType
 	readonly metadata: AgentMetadata
 	protected log: Logger
+	/**
+	 * The logger bound at construction, before any run id exists. `this.log`
+	 * is rebound to a CHILD of this on every `bindRun` call — never the other
+	 * way — so `forRun()` (which builds a fresh shell from `this.metadata`)
+	 * can hand the new instance the same base identity without also handing
+	 * it a stale run id from whichever run happened to be live last.
+	 */
+	private readonly baseLog: Logger
 	protected abortController: AbortController
 	private readonly invocationLock: InvocationLock
 
@@ -43,14 +54,16 @@ export abstract class AbstractAgent<
 
 	protected currentRunId?: RunId
 
-	constructor(metadata: AgentMetadata) {
+	constructor(metadata: AgentMetadata, log?: Logger) {
 		this.metadata = metadata
 		this.abortController = new AbortController()
 		this.invocationLock = new InvocationLock()
-		this.log = getRootLogger().child({
-			component: `Agent:${metadata.type}`,
-			agentId: metadata.id,
+		this.baseLog = resolveLogger(log).child({
+			[SCOPE_ATTRIBUTE]: 'agents',
+			[NAMZU.AGENT_TYPE]: metadata.type,
+			[GENAI.AGENT_ID]: metadata.id,
 		})
+		this.log = this.baseLog
 	}
 
 	abstract run(input: AgentInput, config: TConfig, listener?: RunEventListener): Promise<TResult>
@@ -76,14 +89,17 @@ export abstract class AbstractAgent<
 	 */
 	forRun(): this {
 		try {
-			const Ctor = this.constructor as unknown as new (metadata: AgentMetadata) => this
-			return new Ctor(this.metadata)
+			const Ctor = this.constructor as unknown as new (
+				metadata: AgentMetadata,
+				log?: Logger,
+			) => this
+			return new Ctor(this.metadata, this.baseLog)
 		} catch (err) {
 			this.log.warn(
 				'Could not build a per-run shell; concurrent runs of this agent will still be refused',
 				{
-					agentId: this.metadata.id,
-					error: err instanceof Error ? err.message : String(err),
+					[GENAI.AGENT_ID]: this.metadata.id,
+					'exception.message': err instanceof Error ? err.message : String(err),
 				},
 			)
 			return this
@@ -164,8 +180,8 @@ export abstract class AbstractAgent<
 		const inflight = this.inflightByKey.get(key)
 		if (inflight) {
 			this.log.info('Joining an invocation already running under this key', {
-				agentId: this.metadata.id,
-				idempotencyKey: key,
+				[GENAI.AGENT_ID]: this.metadata.id,
+				'namzu.agents.idempotency_key': key,
 			})
 			return inflight as Promise<T>
 		}
@@ -181,8 +197,17 @@ export abstract class AbstractAgent<
 		}
 	}
 
-	async cancel(): Promise<void> {
-		this.abortController.abort()
+	/**
+	 * `cause` is optional and has no default, deliberately. An operator
+	 * calling this IS the `'user'` case, but a library calling it on the
+	 * operator's behalf is not — and a default would attribute every
+	 * unlabelled cancellation to a person who did not press anything.
+	 *
+	 * Children get `'parent'` regardless of what stopped this run: from a
+	 * child's side, the fact is that its parent went away.
+	 */
+	async cancel(cause?: CancelCause): Promise<void> {
+		this.abortController.abort(cause ? new RunCancelled(cause) : undefined)
 
 		if (this.agentManager && this.currentRunId) {
 			this.agentManager.cancelAll(this.currentRunId)
@@ -197,6 +222,34 @@ export abstract class AbstractAgent<
 		return generateRunId()
 	}
 
+	/**
+	 * Rebind this instance's logger to a specific run, so every record
+	 * `this.log` writes for the DURATION of that run carries `namzu.run.id` —
+	 * and every record after the NEXT call carries that run's id, not this
+	 * one.
+	 *
+	 * Constructor-time binding was the bug this exists to fix: an agent
+	 * constructed once and invoked twice (`forRun` aside — a host is free to
+	 * reuse one instance across sequential runs, and every concrete `run()`
+	 * takes fresh `input`/`config` precisely to allow it) held ONE logger for
+	 * its whole lifetime, so a warning from run two carried run one's id, or
+	 * none. Every concrete `run()` implementation calls this before touching
+	 * `this.log`, right after resolving the run's id — see `RouterAgent`,
+	 * `PipelineAgent`, `SupervisorAgent` and `ReactiveAgent`.
+	 *
+	 * `log` lets a per-run override (`BaseAgentConfig.logger`, a host setting
+	 * on ONE call to `.run()`) win over the agent's construction-time base,
+	 * without reconstructing the agent to get it.
+	 *
+	 * Also the one place `currentRunId` is actually assigned. It was declared
+	 * and read by `cancel()` but never written — a run could never be
+	 * cancelled by id because nothing ever recorded which run was current.
+	 */
+	protected bindRun(runId: RunId, log?: Logger): void {
+		this.currentRunId = runId
+		this.log = (log ?? this.baseLog).child({ [NAMZU.RUN_ID]: runId })
+	}
+
 	protected createEmptyResult(runId: RunId, startTime: number): BaseAgentResult {
 		return {
 			runId,
@@ -215,7 +268,7 @@ export abstract class AbstractAgent<
 			await listener(event)
 		} catch (err) {
 			this.log.error('Event listener error', {
-				error: toErrorMessage(err),
+				'exception.message': toErrorMessage(err),
 			})
 		}
 	}