@danceiny/gotry 0.0.1-rc.8 → 0.2.0-rc.27

package/dist/capabilities/ground-transfer.js

@@ -0,0 +1,509 @@
+/**
+ * Bounded ground-transfer seam for explicit airport/station coordinates.
+ *
+ * This capability owns only the boundary between a public
+ * `map_driving_route` result and the deterministic candidate input. It never
+ * calls a map client directly, never writes shared state, and never supplies
+ * a price: the selected candidate transfer keeps its static `priceCny`.
+ *
+ * Each `ground_transfer` request resolves two deterministic directions —
+ * outbound (origin → destination) and return (destination → origin) — and
+ * binds the resulting route minutes to the candidate transfer as
+ * `minutesOut` / `minutesRet` overrides consumed by the solver / arithmetic
+ * layer. Cache, freshness, and fallback are isolated per direction so a
+ * miss / error / stale / mismatch in one direction never borrows the
+ * dynamic value of the other.
+ */
+import { ToolCallId } from '@deepseek-ai/dsh-llm';
+export const GROUND_TRANSFER_MODE = 'driving';
+export const GROUND_TRANSFER_POSITION = 'destination';
+export const GROUND_TRANSFER_STATIC_MODE = 'taxi';
+export const GROUND_TRANSFER_STATIC_MODE_MISMATCH = 'ground_transfer_static_mode_mismatch';
+export const GROUND_TRANSFER_STATIC_PRICE_EVIDENCE = '[静态包:估算]';
+export const GROUND_TRANSFER_DEFAULT_MAX_AGE_S = 15 * 60;
+const GROUND_TRANSFER_CACHE_LIMIT = 32;
+function asRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function coordinate(value) {
+    const record = asRecord(value);
+    const longitude = record?.['longitude'];
+    const latitude = record?.['latitude'];
+    if (typeof longitude !== 'number' || !Number.isFinite(longitude) || longitude < -180 || longitude > 180
+        || typeof latitude !== 'number' || !Number.isFinite(latitude) || latitude < -90 || latitude > 90)
+        return null;
+    return { longitude, latitude };
+}
+function coordinatePair(value) {
+    const record = asRecord(value);
+    if (!record)
+        return null;
+    const origin = coordinate(record['origin']);
+    const destination = coordinate(record['destination']);
+    if (origin === null || destination === null)
+        return null;
+    return { origin, destination };
+}
+function coordinateText(value) {
+    return `${String(value.longitude)},${String(value.latitude)}`;
+}
+function cacheKey(direction) {
+    return JSON.stringify({
+        mode: GROUND_TRANSFER_MODE,
+        direction: direction.direction,
+        origin: direction.origin,
+        destination: direction.destination,
+    });
+}
+function nowMs(clock) {
+    const value = clock().getTime();
+    if (!Number.isFinite(value))
+        throw new Error('ground-transfer clock returned an invalid date');
+    return value;
+}
+function asOf(clock) {
+    return new Date(nowMs(clock)).toISOString();
+}
+function safeErrorMessage(value) {
+    const message = value instanceof Error ? value.message : String(value);
+    return message.replace(/[\r\n]+/g, ' ').trim().slice(0, 400) || 'unknown provider error';
+}
+function staticCache(status = 'bypass') {
+    return { status, ageS: null, asOf: null };
+}
+function notAppliedBase(parts) {
+    return {
+        requestedMode: parts.requestedMode,
+        requestedPosition: parts.requestedPosition,
+        provenance: 'none',
+        asOf: null,
+        freshness: 'not_attempted',
+        cache: staticCache('bypass'),
+        evidenceClass: 'none',
+    };
+}
+function staticDirectionResolution(direction, staticMinutes, reason) {
+    return {
+        applied: false,
+        direction,
+        staticMinutes,
+        provenance: 'static-transfer-pack',
+        asOf: null,
+        freshness: 'fallback',
+        cache: staticCache('bypass'),
+        evidenceClass: 'static_transfer_estimate',
+        fallbackReason: reason,
+    };
+}
+function parseRequest(value) {
+    const record = asRecord(value);
+    if (!record) {
+        return {
+            candidateId: null,
+            transferIndex: null,
+            requestedMode: null,
+            requestedPosition: null,
+            outbound: null,
+            ret: null,
+            invalidReason: 'ground_transfer_request_invalid:expected an object',
+        };
+    }
+    const candidateId = typeof record['candidate_id'] === 'string' && record['candidate_id'].trim()
+        ? record['candidate_id']
+        : null;
+    const transferIndex = Number.isInteger(record['transfer_index']) && Number(record['transfer_index']) >= 0
+        ? Number(record['transfer_index'])
+        : null;
+    const requestedMode = typeof record['mode'] === 'string' && record['mode'].trim()
+        ? record['mode']
+        : null;
+    const requestedPosition = typeof record['position'] === 'string' && record['position'].trim()
+        ? record['position']
+        : null;
+    let outbound = null;
+    let ret = null;
+    if (record['outbound'] !== undefined || record['return'] !== undefined) {
+        outbound = coordinatePair(record['outbound']);
+        ret = coordinatePair(record['return']);
+    }
+    else {
+        // Legacy single-pair shape: outbound = origin/destination; return = the
+        // swapped pair. Keeps pre-#364 payloads behavior-compatible.
+        const legacyOrigin = coordinate(record['origin']);
+        const legacyDestination = coordinate(record['destination']);
+        if (legacyOrigin && legacyDestination) {
+            outbound = { origin: legacyOrigin, destination: legacyDestination };
+            ret = { origin: legacyDestination, destination: legacyOrigin };
+        }
+    }
+    let invalidReason;
+    if (candidateId === null)
+        invalidReason = 'ground_transfer_binding_invalid:candidate_id is required';
+    else if (transferIndex === null)
+        invalidReason = 'ground_transfer_binding_invalid:transfer_index must be a non-negative integer';
+    else if (requestedPosition !== GROUND_TRANSFER_POSITION)
+        invalidReason = `unsupported_ground_transfer_position:${requestedPosition ?? 'unknown'}`;
+    else if (requestedMode !== GROUND_TRANSFER_MODE)
+        invalidReason = `unsupported_ground_transfer_mode:${requestedMode ?? 'unknown'}`;
+    else if (outbound === null || ret === null)
+        invalidReason = 'invalid_ground_transfer_coordinates:longitude/latitude must be finite and in range';
+    return {
+        candidateId,
+        transferIndex,
+        requestedMode,
+        requestedPosition,
+        outbound,
+        ret,
+        invalidReason,
+    };
+}
+function completeRequest(parts) {
+    if (parts.invalidReason || parts.candidateId === null || parts.transferIndex === null
+        || parts.requestedMode !== GROUND_TRANSFER_MODE || parts.requestedPosition !== GROUND_TRANSFER_POSITION
+        || parts.outbound === null || parts.ret === null)
+        return null;
+    return {
+        candidateId: parts.candidateId,
+        transferIndex: parts.transferIndex,
+        mode: GROUND_TRANSFER_MODE,
+        position: GROUND_TRANSFER_POSITION,
+        outbound: { direction: 'outbound', origin: parts.outbound.origin, destination: parts.outbound.destination },
+        ret: { direction: 'return', origin: parts.ret.origin, destination: parts.ret.destination },
+    };
+}
+function parseRouteResult(value) {
+    const record = asRecord(value);
+    if (!record)
+        throw new Error('map_driving_route returned an invalid public result');
+    const provider = record?.['provider'];
+    const distanceM = record?.['distanceM'];
+    const durationS = record?.['durationS'];
+    if (typeof provider !== 'string' || provider.trim() === ''
+        || typeof distanceM !== 'number' || !Number.isFinite(distanceM) || distanceM < 0
+        || typeof durationS !== 'number' || !Number.isFinite(durationS) || durationS < 0
+        // A positive distance cannot be covered in zero time: such a response is
+        // a self-contradictory route fact, not a credible provider hit. It falls
+        // into the explicit provider-miss fallback instead of silently binding
+        // zero minutes into the solver.
+        || (distanceM > 0 && durationS === 0))
+        throw new Error('map_driving_route returned an invalid public result');
+    return {
+        provider,
+        distanceM,
+        durationS,
+        ...(typeof record['polyline'] === 'string' ? { polyline: record['polyline'] } : {}),
+        ...(Array.isArray(record['steps']) ? { steps: record['steps'] } : {}),
+    };
+}
+function buildRouteFact(direction, route, clock, cache) {
+    return {
+        direction: direction.direction,
+        origin: direction.origin,
+        destination: direction.destination,
+        mode: GROUND_TRANSFER_MODE,
+        provider: route.provider,
+        distanceM: route.distanceM,
+        durationS: route.durationS,
+        durationMin: Math.round(route.durationS / 60),
+        asOf: asOf(clock),
+        provenance: 'map_driving_route',
+        freshness: cache.status === 'hit' ? 'cache_hit' : 'fresh',
+        cache,
+        evidenceClass: 'public_map_route_estimate',
+        trafficStatus: 'not-live-route-estimate',
+    };
+}
+function selectionFor(candidates, parts) {
+    if (parts.candidateId === null || parts.transferIndex === null)
+        return null;
+    const matching = candidates
+        .map((candidate, index) => ({ candidate, index }))
+        .filter(({ candidate }) => candidate.id === parts.candidateId);
+    if (matching.length !== 1)
+        return null;
+    const match = matching[0];
+    const transfer = match.candidate.destTransfers[parts.transferIndex];
+    if (!transfer || typeof transfer.mode !== 'string' || !Number.isFinite(transfer.minutes) || transfer.minutes < 0 || !Number.isFinite(transfer.priceCny) || transfer.priceCny < 0)
+        return null;
+    return {
+        candidateIndex: match.index,
+        selection: {
+            candidateId: parts.candidateId,
+            transferIndex: parts.transferIndex,
+            staticMode: transfer.mode,
+            staticMinutes: transfer.minutes,
+            staticPriceCny: transfer.priceCny,
+        },
+    };
+}
+async function resolveDirection(direction, staticMinutes, provider, clock, cache, maxEntries, context) {
+    const key = cacheKey(direction);
+    const currentMs = nowMs(clock);
+    const cached = cache.get(key);
+    if (cached) {
+        const ageS = Math.max(0, currentMs - cached.storedAtMs) / 1000;
+        if (ageS <= GROUND_TRANSFER_DEFAULT_MAX_AGE_S) {
+            const hitCache = { status: 'hit', ageS, asOf: cached.fact.asOf };
+            const hitFact = { ...cached.fact, freshness: 'cache_hit', cache: hitCache };
+            return {
+                applied: true,
+                direction: direction.direction,
+                minutes: hitFact.durationMin,
+                staticMinutes,
+                provenance: 'map_driving_route',
+                asOf: hitFact.asOf,
+                freshness: 'cache_hit',
+                cache: hitCache,
+                evidenceClass: 'public_map_route_estimate',
+                routeFact: hitFact,
+            };
+        }
+    }
+    const requestForProvider = {
+        origin: coordinateText(direction.origin),
+        destination: coordinateText(direction.destination),
+        mode: GROUND_TRANSFER_MODE,
+    };
+    try {
+        const raw = await provider(requestForProvider, {
+            signal: context.signal ?? new AbortController().signal,
+            execution: context.execution,
+        });
+        const route = parseRouteResult(raw);
+        const cacheInfo = {
+            status: cached ? 'requery' : 'miss',
+            ageS: 0,
+            asOf: null,
+        };
+        const fact = buildRouteFact(direction, route, clock, cacheInfo);
+        cacheInfo.asOf = fact.asOf;
+        const entry = { fact, storedAtMs: currentMs };
+        if (cache.size >= maxEntries && !cache.has(key)) {
+            const oldest = cache.keys().next().value;
+            if (typeof oldest === 'string')
+                cache.delete(oldest);
+        }
+        cache.set(key, entry);
+        return {
+            applied: true,
+            direction: direction.direction,
+            minutes: fact.durationMin,
+            staticMinutes,
+            provenance: 'map_driving_route',
+            asOf: fact.asOf,
+            freshness: 'fresh',
+            cache: cacheInfo,
+            evidenceClass: 'public_map_route_estimate',
+            routeFact: fact,
+        };
+    }
+    catch (error) {
+        const detail = safeErrorMessage(error);
+        return {
+            applied: false,
+            direction: direction.direction,
+            staticMinutes,
+            provenance: 'static-transfer-pack',
+            asOf: null,
+            freshness: 'fallback',
+            cache: staticCache(cached ? 'stale' : 'bypass'),
+            evidenceClass: 'static_transfer_estimate',
+            fallbackReason: cached
+                ? `stale_route_requery_error:${direction.direction}:${detail}`
+                : `map_driving_route_provider_error:${direction.direction}:${detail}`,
+        };
+    }
+}
+export function createGroundTransferResolver(options) {
+    const clock = options.clock ?? (() => new Date());
+    const maxEntries = Number.isInteger(options.maxEntries) && Number(options.maxEntries) > 0
+        ? Number(options.maxEntries)
+        : GROUND_TRANSFER_CACHE_LIMIT;
+    const cache = new Map();
+    return {
+        async resolve(request, selection, context = {}) {
+            const [outbound, ret] = await Promise.all([
+                resolveDirection(request.outbound, selection.staticMinutes, options.provider, clock, cache, maxEntries, context),
+                resolveDirection(request.ret, selection.staticMinutes, options.provider, clock, cache, maxEntries, context),
+            ]);
+            const applied = outbound.applied || ret.applied;
+            // Aggregate fields are a summary only: per-direction objects above are
+            // the authoritative per-direction record. A full cache hit keeps the
+            // legacy aggregate semantics ('cache_hit'), a re-query keeps 'requery'.
+            const aggregateProvenance = applied ? 'map_driving_route' : 'static-transfer-pack';
+            const aggregateEvidenceClass = applied ? 'public_map_route_estimate' : 'static_transfer_estimate';
+            const aggregateFreshness = !applied
+                ? 'fallback'
+                : outbound.freshness === 'fresh' || ret.freshness === 'fresh'
+                    ? 'fresh'
+                    : 'cache_hit';
+            const statuses = [outbound.cache.status, ret.cache.status];
+            const aggregateCache = !applied
+                ? staticCache('bypass')
+                : {
+                    status: statuses.includes('hit') ? 'hit' : statuses.includes('requery') ? 'requery' : 'miss',
+                    ageS: 0,
+                    asOf: null,
+                };
+            const aggregateAsOf = applied ? (outbound.asOf ?? ret.asOf) : null;
+            const resolution = {
+                applied,
+                candidateId: selection.candidateId,
+                transferIndex: selection.transferIndex,
+                requestedMode: request.mode,
+                requestedPosition: request.position,
+                staticMode: selection.staticMode,
+                staticMinutes: selection.staticMinutes,
+                priceCny: selection.staticPriceCny,
+                priceEvidence: GROUND_TRANSFER_STATIC_PRICE_EVIDENCE,
+                provenance: aggregateProvenance,
+                asOf: aggregateAsOf,
+                freshness: aggregateFreshness,
+                cache: aggregateCache,
+                evidenceClass: aggregateEvidenceClass,
+                outbound,
+                return: ret,
+            };
+            if (outbound.applied)
+                resolution.outboundMinutes = outbound.minutes;
+            if (ret.applied)
+                resolution.returnMinutes = ret.minutes;
+            if (!applied) {
+                resolution.fallbackReason = `both_directions_failed:${outbound.fallbackReason ?? 'unknown'};${ret.fallbackReason ?? 'unknown'}`;
+            }
+            return resolution;
+        },
+    };
+}
+/**
+ * Delegate through the registered public map tool. The dsh-tools types expose
+ * nested execution explicitly, so the current root/agent/signal are carried
+ * into the sub-dispatch instead of calling a private map client.
+ */
+export function createPublicMapDrivingRouteProvider(ctx) {
+    return async (request, context) => {
+        const execution = context.execution;
+        if (!execution)
+            throw new Error('GROUND_TRANSFER_NESTED_EXECUTION_UNSUPPORTED: current tool execution context is unavailable');
+        const tools = ctx.tools;
+        if (typeof tools?.execute !== 'function' || typeof tools?.get !== 'function') {
+            throw new Error('GROUND_TRANSFER_NESTED_EXECUTION_UNSUPPORTED: host must expose dsh-tools ToolRuntime.execute/get');
+        }
+        if (!tools.get('map_driving_route', execution.agent)) {
+            throw new Error('GROUND_TRANSFER_PUBLIC_MAP_TOOL_UNAVAILABLE: map_driving_route is not registered in the current tool scope');
+        }
+        const nested = {
+            callId: ToolCallId(`${String(execution.callId)}:ground-transfer`),
+            rootCallId: execution.rootCallId,
+            name: 'map_driving_route',
+            arguments: { origin: request.origin, destination: request.destination },
+            ...(execution.agent !== undefined ? { agent: execution.agent } : {}),
+            parent: execution.token,
+            signal: execution.signal,
+        };
+        const result = await tools.execute(nested);
+        if (result.isError)
+            throw new Error(`map_driving_route failed: ${result.error.message}`);
+        return parseRouteResult(result.value);
+    };
+}
+/** Resolve and patch exactly one named transfer position before solver entry. */
+export async function resolveGroundTransferPayload(rawRequest, candidates, resolver, context) {
+    const parts = parseRequest(rawRequest);
+    const bound = selectionFor(candidates, parts);
+    if (!bound) {
+        const base = notAppliedBase(parts);
+        return {
+            candidates: [...candidates],
+            resolution: {
+                ...base,
+                applied: false,
+                ...(parts.candidateId !== null ? { candidateId: parts.candidateId } : {}),
+                ...(parts.transferIndex !== null ? { transferIndex: parts.transferIndex } : {}),
+                outbound: staticDirectionResolution('outbound', Number.NaN, 'ground_transfer_binding_mismatch'),
+                return: staticDirectionResolution('return', Number.NaN, 'ground_transfer_binding_mismatch'),
+                fallbackReason: 'ground_transfer_binding_mismatch: candidate_id and transfer_index must identify exactly one valid static transfer',
+            },
+        };
+    }
+    const complete = completeRequest(parts);
+    if (!complete) {
+        return {
+            candidates: [...candidates],
+            resolution: {
+                applied: false,
+                candidateId: bound.selection.candidateId,
+                transferIndex: bound.selection.transferIndex,
+                requestedMode: parts.requestedMode,
+                requestedPosition: parts.requestedPosition,
+                staticMode: bound.selection.staticMode,
+                staticMinutes: bound.selection.staticMinutes,
+                priceCny: bound.selection.staticPriceCny,
+                priceEvidence: GROUND_TRANSFER_STATIC_PRICE_EVIDENCE,
+                provenance: 'static-transfer-pack',
+                asOf: null,
+                freshness: 'fallback',
+                cache: staticCache('bypass'),
+                evidenceClass: 'static_transfer_estimate',
+                outbound: staticDirectionResolution('outbound', bound.selection.staticMinutes, parts.invalidReason ?? 'ground_transfer_request_invalid'),
+                return: staticDirectionResolution('return', bound.selection.staticMinutes, parts.invalidReason ?? 'ground_transfer_request_invalid'),
+                fallbackReason: `${parts.invalidReason ?? 'ground_transfer_request_invalid'}; static transfer minutes and price preserved`,
+            },
+        };
+    }
+    if (bound.selection.staticMode !== GROUND_TRANSFER_STATIC_MODE) {
+        const reason = `${GROUND_TRANSFER_STATIC_MODE_MISMATCH}: mode=${bound.selection.staticMode}; only taxi accepts a driving route; static transfer preserved`;
+        return {
+            candidates: [...candidates],
+            resolution: {
+                applied: false,
+                candidateId: bound.selection.candidateId,
+                transferIndex: bound.selection.transferIndex,
+                requestedMode: parts.requestedMode,
+                requestedPosition: parts.requestedPosition,
+                staticMode: bound.selection.staticMode,
+                staticMinutes: bound.selection.staticMinutes,
+                priceCny: bound.selection.staticPriceCny,
+                priceEvidence: GROUND_TRANSFER_STATIC_PRICE_EVIDENCE,
+                provenance: 'static-transfer-pack',
+                asOf: null,
+                freshness: 'not_attempted',
+                cache: staticCache('bypass'),
+                evidenceClass: 'static_transfer_estimate',
+                outbound: staticDirectionResolution('outbound', bound.selection.staticMinutes, reason),
+                return: staticDirectionResolution('return', bound.selection.staticMinutes, reason),
+                fallbackReason: reason,
+            },
+        };
+    }
+    const resolution = await resolver.resolve(complete, bound.selection, context);
+    if (!resolution.applied) {
+        return { candidates: [...candidates], resolution };
+    }
+    const patched = candidates.map((candidate, candidateIndex) => {
+        if (candidateIndex !== bound.candidateIndex)
+            return candidate;
+        const destTransfers = candidate.destTransfers.map((transfer, transferIndex) => {
+            if (transferIndex !== bound.selection.transferIndex)
+                return transfer;
+            const next = { ...transfer };
+            if (resolution.outboundMinutes !== undefined)
+                next['minutesOut'] = resolution.outboundMinutes;
+            if (resolution.returnMinutes !== undefined)
+                next['minutesRet'] = resolution.returnMinutes;
+            return next;
+        });
+        return { ...candidate, destTransfers };
+    });
+    return { candidates: patched, resolution };
+}
+export function exposeGroundTransferEvidence(result, resolution) {
+    const verdicts = Array.isArray(result['verdicts'])
+        ? result['verdicts'].map(verdict => resolution.candidateId !== undefined && verdict['candidate_id'] === resolution.candidateId
+            ? { ...verdict, transfer_evidence: resolution }
+            : verdict)
+        : result['verdicts'];
+    return { ...result, verdicts, ground_transfer: resolution };
+}