@haaaiawd/second-nature 0.1.42 → 0.1.50

package/dist/src/connectors/base/map-life-evidence.js

@@ -0,0 +1,137 @@
+const PLATFORM_ARRAY_KEYS = [
+    "posts",
+    "nodes",
+    "agents",
+    "edges",
+    "results",
+    "entries",
+];
+function tryExtractId(item) {
+    if (item && typeof item === "object" && "id" in item) {
+        const id = item.id;
+        if (id !== undefined && id !== null)
+            return String(id);
+    }
+    return undefined;
+}
+function tryExtractUri(item, platformId, fallbackId) {
+    if (item && typeof item === "object") {
+        const record = item;
+        for (const key of ["url", "uri", "link"]) {
+            const value = record[key];
+            if (typeof value === "string" && value.trim().length > 0) {
+                return value;
+            }
+        }
+    }
+    return `platform://${platformId}/item/${encodeURIComponent(fallbackId)}`;
+}
+function extractFromPlatformArray(platformId, record, observedAt) {
+    for (const key of PLATFORM_ARRAY_KEYS) {
+        const arr = record[key];
+        if (Array.isArray(arr) && arr.length > 0) {
+            const out = [];
+            for (let index = 0; index < arr.length; index += 1) {
+                const item = arr[index];
+                const id = tryExtractId(item) ?? `${platformId}-${key}-${index}`;
+                const uri = tryExtractUri(item, platformId, id);
+                out.push({
+                    id,
+                    kind: "platform_item",
+                    uri,
+                    observedAt,
+                });
+            }
+            if (out.length > 0)
+                return out;
+        }
+    }
+    return undefined;
+}
+function extractSourceRefs(platformId, data, observedAt) {
+    if (data && typeof data === "object") {
+        const record = data;
+        if (record.data && typeof record.data === "object") {
+            const nested = extractSourceRefs(platformId, record.data, observedAt);
+            if (nested.length > 0)
+                return nested;
+        }
+        if (Array.isArray(record.sourceRefs)) {
+            const out = [];
+            for (const item of record.sourceRefs) {
+                if (item && typeof item === "object" && "uri" in item && "id" in item) {
+                    const ref = item;
+                    out.push({
+                        id: String(ref.id),
+                        kind: ref.kind ?? "platform_item",
+                        uri: String(ref.uri),
+                        excerptHash: ref.excerptHash !== undefined ? String(ref.excerptHash) : undefined,
+                        observedAt: ref.observedAt !== undefined ? String(ref.observedAt) : observedAt,
+                    });
+                }
+            }
+            if (out.length > 0)
+                return out;
+        }
+        if (Array.isArray(record.items)) {
+            return record.items.map((item, index) => {
+                const id = item && typeof item === "object" && "id" in item
+                    ? String(item.id)
+                    : `${platformId}-item-${index}`;
+                return {
+                    id,
+                    kind: "platform_item",
+                    uri: `platform://${platformId}/item/${encodeURIComponent(id)}`,
+                    observedAt,
+                };
+            });
+        }
+        const platformRefs = extractFromPlatformArray(platformId, record, observedAt);
+        if (platformRefs)
+            return platformRefs;
+    }
+    return [];
+}
+function resolveEvidenceType(intent) {
+    if (intent === "feed.read")
+        return "platform_browse";
+    if (intent === "work.discover")
+        return "task_discovery";
+    return null;
+}
+function resolveSensitivity(intent, explicit) {
+    if (explicit)
+        return explicit;
+    if (intent === "message.send" || intent === "comment.reply")
+        return "private";
+    return "public";
+}
+/**
+ * Produce a single life-evidence candidate from a connector outcome, or null if not mappable.
+ */
+export function mapLifeEvidence(input) {
+    if (input.result.status !== "success") {
+        return null;
+    }
+    if (input.intent === "message.send") {
+        return null;
+    }
+    const evidenceType = resolveEvidenceType(input.intent);
+    if (!evidenceType) {
+        return null;
+    }
+    const observedAt = input.observedAt ?? new Date().toISOString();
+    const refs = extractSourceRefs(input.platformId, input.result.data, observedAt);
+    if (refs.length === 0) {
+        return null;
+    }
+    return {
+        timestamp: observedAt,
+        evidenceType,
+        platformId: input.platformId,
+        summary: `${input.platformId}:${input.intent}`,
+        sourceRefs: refs,
+        sensitivity: resolveSensitivity(input.intent, input.sensitivityOverride),
+        producer: "connector-system",
+    };
+}

package/dist/src/connectors/base/policy-layer.js

@@ -0,0 +1,202 @@
+import { classifyFailure } from "./failure-taxonomy.js";
+import { enforceExecutionPolicy } from "./execution-policy.js";
+const DEFAULT_RETRY_MAX = 3;
+const DEFAULT_BASE_DELAY_MS = 1000;
+const DEFAULT_MAX_DELAY_MS = 30000;
+function resolveRetryPolicy(input) {
+    return {
+        maxRetries: input?.maxRetries ?? DEFAULT_RETRY_MAX,
+        baseDelayMs: input?.baseDelayMs ?? DEFAULT_BASE_DELAY_MS,
+        maxDelayMs: input?.maxDelayMs ?? DEFAULT_MAX_DELAY_MS,
+        jitter: input?.jitter ?? true,
+    };
+}
+function computeRetryDelayMs(attempt, policy, retryAfterMs) {
+    if (typeof retryAfterMs === "number" && retryAfterMs > 0) {
+        return retryAfterMs;
+    }
+    const base = Math.min(policy.baseDelayMs * 2 ** Math.max(0, attempt - 1), policy.maxDelayMs);
+    if (!policy.jitter)
+        return base;
+    return Math.floor(base * 0.8 + Math.random() * base * 0.4);
+}
+async function sleep(ms) {
+    if (ms <= 0)
+        return;
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+function makeTraceId(request, plan) {
+    return `${request.platformId}:${request.intent}:${plan.channel}:${Date.now()}`;
+}
+function resolveIdentity(request) {
+    if (!request.decisionId || !request.intentId) {
+        throw new Error("connector_policy_missing_decision_or_intent_identity");
+    }
+    return {
+        decisionId: request.decisionId,
+        intentId: request.intentId,
+    };
+}
+function isDegradedChannel(channel) {
+    return channel === "cli" || channel === "skill" || channel === "browser";
+}
+function adaptProtocolErrors(error) {
+    if (!error || typeof error !== "object") {
+        return error;
+    }
+    const record = error;
+    const detail = typeof record.detail === "string" ? record.detail : "";
+    if (detail === "node_secret_required") {
+        return { code: "verification_required", detail };
+    }
+    if (detail === "bundle_required") {
+        return { code: "protocol_mismatch", detail };
+    }
+    if (detail === "asset_id mismatch") {
+        return { code: "protocol_mismatch", detail };
+    }
+    return error;
+}
+export function createConnectorPolicyLayer(ctx) {
+    const retryPolicy = resolveRetryPolicy(ctx.retryPolicy);
+    const allowDegradedFallback = ctx.allowDegradedFallback ?? (() => true);
+    return {
+        async executeWithPolicy(intent, request) {
+            if (ctx.cooldownPort) {
+                const cooldown = await ctx.cooldownPort.isBlocked(request.platformId, intent);
+                if (cooldown.blocked) {
+                    return {
+                        status: "terminal_failure",
+                        failureClass: "cooldown_blocked",
+                        retryAfterMs: cooldown.retryAfterMs,
+                        metadata: {
+                            platformId: request.platformId,
+                            channel: request.preferredChannel ?? "api_rest",
+                            latencyMs: 0,
+                        },
+                    };
+                }
+            }
+            const identity = resolveIdentity(request);
+            let plan;
+            try {
+                plan = await ctx.routePlanner.planRoute(intent, request);
+            }
+            catch (error) {
+                const failure = classifyFailure(error);
+                return {
+                    status: "terminal_failure",
+                    failureClass: failure.class,
+                    retryAfterMs: failure.retryAfterMs,
+                    metadata: {
+                        platformId: request.platformId,
+                        channel: request.preferredChannel ?? "api_rest",
+                        latencyMs: 0,
+                    },
+                };
+            }
+            if (isDegradedChannel(plan.channel) && !allowDegradedFallback(plan, request)) {
+                return {
+                    status: "terminal_failure",
+                    failureClass: "protocol_mismatch",
+                    metadata: {
+                        platformId: request.platformId,
+                        channel: plan.channel,
+                        latencyMs: 0,
+                        degraded: true,
+                    },
+                };
+            }
+            const policyGate = await enforceExecutionPolicy(plan, intent, request, {
+                effectCommitLedger: ctx.effectCommitLedger,
+            });
+            if (policyGate.skipAdapter && policyGate.existingOutcomeRef) {
+                return {
+                    status: "success",
+                    data: { replayedCommit: true, outcomeRef: policyGate.existingOutcomeRef },
+                    metadata: {
+                        platformId: request.platformId,
+                        channel: plan.channel,
+                        latencyMs: 0,
+                        degraded: plan.degraded,
+                    },
+                };
+            }
+            let lastFailure;
+            for (let attempt = 1; attempt <= retryPolicy.maxRetries; attempt += 1) {
+                const traceId = `${makeTraceId(request, plan)}:${attempt}`;
+                if (ctx.telemetry) {
+                    await ctx.telemetry.startAttempt({
+                        traceId,
+                        decisionId: identity.decisionId,
+                        intentId: identity.intentId,
+                        platformId: request.platformId,
+                        capability: request.intent,
+                        channel: plan.channel,
+                        retryPolicy: JSON.stringify(retryPolicy),
+                        idempotencyKey: request.idempotencyKey,
+                    });
+                }
+                const raw = await ctx.executionRunner.run(plan, request);
+                if (raw.success) {
+                    if (ctx.telemetry) {
+                        await ctx.telemetry.completeAttempt(traceId, "succeeded");
+                    }
+                    return {
+                        status: "success",
+                        data: raw.payload,
+                        metadata: {
+                            platformId: raw.platformId,
+                            channel: raw.channel,
+                            latencyMs: raw.latencyMs,
+                            degraded: raw.degraded,
+                        },
+                    };
+                }
+                const classified = classifyFailure(adaptProtocolErrors(raw.error));
+                lastFailure = {
+                    failureClass: classified.class,
+                    retryAfterMs: classified.retryAfterMs,
+                    channel: raw.channel,
+                };
+                if (ctx.telemetry) {
+                    await ctx.telemetry.completeAttempt(traceId, "failed", undefined, classified.class);
+                }
+                if (ctx.cooldownPort) {
+                    await ctx.cooldownPort.markFailure(request.platformId, intent, classified.class, classified.retryAfterMs);
+                }
+                const isRetryable = classified.retryable;
+                const errorDetail = raw.error && typeof raw.error === "object" && "detail" in raw.error
+                    ? String(raw.error.detail)
+                    : undefined;
+                if (!isRetryable || attempt >= retryPolicy.maxRetries) {
+                    return {
+                        status: "terminal_failure",
+                        failureClass: classified.class,
+                        retryAfterMs: classified.retryAfterMs,
+                        metadata: {
+                            platformId: raw.platformId,
+                            channel: raw.channel,
+                            latencyMs: raw.latencyMs,
+                            degraded: raw.degraded,
+                            detail: errorDetail,
+                        },
+                    };
+                }
+                const delay = computeRetryDelayMs(attempt, retryPolicy, classified.retryAfterMs);
+                await sleep(delay);
+            }
+            return {
+                status: "terminal_failure",
+                failureClass: lastFailure?.failureClass ?? "unknown_platform_change",
+                retryAfterMs: lastFailure?.retryAfterMs,
+                metadata: {
+                    platformId: request.platformId,
+                    channel: lastFailure?.channel ?? plan.channel,
+                    latencyMs: 0,
+                    degraded: isDegradedChannel(lastFailure?.channel ?? plan.channel),
+                },
+            };
+        },
+    };
+}

package/dist/src/connectors/manifest/manifest-schema.d.ts

@@ -0,0 +1,152 @@
+import { z } from "zod";
+export declare const connectorRunnerKindSchema: z.ZodEnum<{
+    skill: "skill";
+    browser: "browser";
+    declarative_http: "declarative_http";
+    declarative_a2a: "declarative_a2a";
+    declarative_mcp: "declarative_mcp";
+    cli_descriptor: "cli_descriptor";
+    custom_adapter: "custom_adapter";
+    scriptable_node: "scriptable_node";
+}>;
+export type ConnectorRunnerKind = z.infer<typeof connectorRunnerKindSchema>;
+export declare const connectorTrustStatusSchema: z.ZodEnum<{
+    blocked: "blocked";
+    declarative_trusted: "declarative_trusted";
+    custom_adapter_pending_trust: "custom_adapter_pending_trust";
+    trusted_custom_adapter: "trusted_custom_adapter";
+}>;
+export type ConnectorTrustStatus = z.infer<typeof connectorTrustStatusSchema>;
+export declare const capabilityDeclarationSchema: z.ZodObject<{
+    id: z.ZodString;
+    channel: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    sourceRefs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    observedCount: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type ConnectorCapabilityDeclaration = z.infer<typeof capabilityDeclarationSchema>;
+export declare const runnerDeclarationSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        skill: "skill";
+        browser: "browser";
+        declarative_http: "declarative_http";
+        declarative_a2a: "declarative_a2a";
+        declarative_mcp: "declarative_mcp";
+        cli_descriptor: "cli_descriptor";
+        custom_adapter: "custom_adapter";
+        scriptable_node: "scriptable_node";
+    }>;
+    entrypoint: z.ZodOptional<z.ZodString>;
+    config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type ConnectorRunnerDeclaration = z.infer<typeof runnerDeclarationSchema>;
+export declare const credentialRequirementSchema: z.ZodObject<{
+    type: z.ZodString;
+    required: z.ZodDefault<z.ZodBoolean>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CredentialRequirementDeclaration = z.infer<typeof credentialRequirementSchema>;
+export declare const sourceRefPolicySchema: z.ZodObject<{
+    minSourceRefs: z.ZodDefault<z.ZodNumber>;
+    rejectInlineSensitivePayload: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type SourceRefPolicyDeclaration = z.infer<typeof sourceRefPolicySchema>;
+export declare const trustDeclarationSchema: z.ZodObject<{
+    status: z.ZodOptional<z.ZodEnum<{
+        blocked: "blocked";
+        declarative_trusted: "declarative_trusted";
+        custom_adapter_pending_trust: "custom_adapter_pending_trust";
+        trusted_custom_adapter: "trusted_custom_adapter";
+    }>>;
+    override: z.ZodOptional<z.ZodBoolean>;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ConnectorTrustDeclaration = z.infer<typeof trustDeclarationSchema>;
+export declare const connectorManifestV6Schema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"sn.connector.v1">;
+    platformId: z.ZodString;
+    displayName: z.ZodString;
+    family: z.ZodEnum<{
+        custom: "custom";
+        social_community: "social_community";
+        agent_network: "agent_network";
+        work_platform: "work_platform";
+    }>;
+    capabilities: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        channel: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        sourceRefs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        observedCount: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    runner: z.ZodObject<{
+        kind: z.ZodEnum<{
+            skill: "skill";
+            browser: "browser";
+            declarative_http: "declarative_http";
+            declarative_a2a: "declarative_a2a";
+            declarative_mcp: "declarative_mcp";
+            cli_descriptor: "cli_descriptor";
+            custom_adapter: "custom_adapter";
+            scriptable_node: "scriptable_node";
+        }>;
+        entrypoint: z.ZodOptional<z.ZodString>;
+        config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>;
+    credentials: z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        required: z.ZodDefault<z.ZodBoolean>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    sourceRefPolicy: z.ZodObject<{
+        minSourceRefs: z.ZodDefault<z.ZodNumber>;
+        rejectInlineSensitivePayload: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+    trust: z.ZodOptional<z.ZodObject<{
+        status: z.ZodOptional<z.ZodEnum<{
+            blocked: "blocked";
+            declarative_trusted: "declarative_trusted";
+            custom_adapter_pending_trust: "custom_adapter_pending_trust";
+            trusted_custom_adapter: "trusted_custom_adapter";
+        }>>;
+        override: z.ZodOptional<z.ZodBoolean>;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ConnectorManifestV6 = z.infer<typeof connectorManifestV6Schema>;
+export interface ConnectorConflict {
+    platformId: string;
+    existingSource: "built_in" | "workspace";
+    attemptedSource: "built_in" | "workspace";
+    reason: string;
+}
+export interface ConnectorManifestValidationError {
+    platformId?: string;
+    path: string;
+    message: string;
+}
+export interface ConnectorInventoryEntry {
+    platformId: string;
+    source: "built_in" | "workspace";
+    manifestPath?: string;
+    trustStatus: ConnectorTrustStatus;
+    executable: boolean;
+    capabilities: string[];
+    validationErrors: string[];
+    conflict?: ConnectorConflict;
+}
+export interface ConnectorReloadResult {
+    scanned: number;
+    registered: number;
+    skipped: number;
+    conflicts: ConnectorConflict[];
+    validationErrors: ConnectorManifestValidationError[];
+}
+export interface ConnectorRegistrySnapshot {
+    readonly entries: ReadonlyMap<string, ConnectorInventoryEntry>;
+    readonly builtInEntries: ReadonlyMap<string, ConnectorInventoryEntry>;
+    readonly dynamicEntries: ReadonlyMap<string, ConnectorInventoryEntry>;
+    readonly conflicts: readonly ConnectorConflict[];
+    readonly validationErrors: readonly ConnectorManifestValidationError[];
+    readonly createdAt: string;
+}

package/dist/src/connectors/manifest/manifest-schema.js

@@ -0,0 +1,54 @@
+import { z } from "zod";
+export const connectorRunnerKindSchema = z.enum([
+    "declarative_http",
+    "declarative_a2a",
+    "declarative_mcp",
+    "cli_descriptor",
+    "custom_adapter",
+    "skill",
+    "browser",
+    "scriptable_node",
+]);
+export const connectorTrustStatusSchema = z.enum([
+    "declarative_trusted",
+    "custom_adapter_pending_trust",
+    "trusted_custom_adapter",
+    "blocked",
+]);
+export const capabilityDeclarationSchema = z.object({
+    id: z.string().min(1),
+    channel: z.string().optional(),
+    description: z.string().optional(),
+    sourceRefs: z.array(z.string().min(1)).optional(),
+    observedCount: z.number().int().positive().optional(),
+});
+export const runnerDeclarationSchema = z.object({
+    kind: connectorRunnerKindSchema,
+    entrypoint: z.string().optional(),
+    config: z.record(z.string(), z.unknown()).optional(),
+});
+export const credentialRequirementSchema = z.object({
+    type: z.string().min(1),
+    required: z.boolean().default(true),
+    description: z.string().optional(),
+});
+export const sourceRefPolicySchema = z.object({
+    minSourceRefs: z.number().int().min(0).default(1),
+    rejectInlineSensitivePayload: z.boolean().optional(),
+});
+export const trustDeclarationSchema = z.object({
+    status: connectorTrustStatusSchema.optional(),
+    override: z.boolean().optional(),
+    reason: z.string().optional(),
+});
+export const connectorManifestV6Schema = z.object({
+    schemaVersion: z.literal("sn.connector.v1"),
+    platformId: z.string().min(1),
+    displayName: z.string().min(1),
+    family: z.enum(["social_community", "agent_network", "work_platform", "custom"]),
+    capabilities: z.array(capabilityDeclarationSchema).min(1),
+    runner: runnerDeclarationSchema,
+    credentials: z.array(credentialRequirementSchema),
+    sourceRefPolicy: sourceRefPolicySchema,
+    trust: trustDeclarationSchema.optional(),
+});

package/dist/src/connectors/services/connector-executor-adapter.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Adapter: assemble connector-system execution infrastructure into the
+ * ConnectorExecutor interface consumed by EffectDispatcher.
+ *
+ * When credentials / base URLs are missing, returns an honest
+ * terminal_failure instead of throwing so the heartbeat loop stays stable.
+ */
+import type { ConnectorExecutor } from "../base/contract.js";
+export type { ConnectorExecutor } from "../base/contract.js";
+import { type EvoMapSecretPort } from "../agent-network/evomap/adapter.js";
+import type { ObservabilityDatabase } from "../../observability/db/index.js";
+import type { StateDatabase } from "../../storage/db/index.js";
+import { createCredentialVault } from "../../storage/services/credential-vault.js";
+export interface ConnectorExecutorAdapterOptions {
+    stateDb: StateDatabase;
+    observabilityDb: ObservabilityDatabase;
+    workspaceRoot?: string;
+}
+export declare function createEvoMapSecretPort(vault: ReturnType<typeof createCredentialVault>): EvoMapSecretPort;
+export declare function createConnectorExecutorAdapter(options: ConnectorExecutorAdapterOptions): ConnectorExecutor;