digital-tools 2.1.3 → 2.3.0

package/src/function-sugar.ts

@@ -0,0 +1,134 @@
+/**
+ * Sugar factories for the Four Functions (v3 §6).
+ *
+ * Top-level named exports `Code` / `Generative` / `Agentic` / `Human` mint a
+ * typed {@link FunctionRef} from a kind-specific spec. The factory fills in
+ * the discriminator (`kind`) and a deterministic `$id` derived from `name`,
+ * so callers write the minimum possible at the call site:
+ *
+ * ```ts
+ * import { Code, Generative, Agentic, Human } from 'digital-tools'
+ *
+ * const summarize = Generative({ name: 'summarize', modelHint: 'claude-opus-4' })
+ * const reviewer  = Agentic({ name: 'security-review', mode: 'supervised', persona: 'persona:skeptic' })
+ * const signOff   = Human({ name: 'controller-sign-off', rationale: 'regulatory',
+ *                            expirationPolicy: { whenAccuracyExceeds: 0.99, whenSamplesExceed: 500 } })
+ * const compute   = Code({ name: 'compute-vat', handler: (x: { net: number }) => x.net * 0.2 })
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import type {
+  AgenticFunctionRef,
+  CodeFunctionRef,
+  FunctionRef,
+  GenerativeFunctionRef,
+  HumanFunctionRef,
+} from './function-ref.js'
+
+/**
+ * Reduce an arbitrary name to a stable, lowercase, hyphen-joined slug.
+ * Non-ASCII alphanumerics collapse to `-`; leading/trailing `-` are trimmed.
+ */
+function slug(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+/**
+ * Mint a deterministic `fn:<kind>:<slug>` MDXLD `$id`.
+ */
+function mintId(kind: FunctionRef['kind'], name: string): string {
+  return `fn:${kind}:${slug(name)}`
+}
+
+// ============================================================================
+// Code
+// ============================================================================
+
+/**
+ * Spec accepted by the {@link Code} sugar factory. Omits the auto-derived
+ * `$id` and the discriminator `kind`.
+ */
+export type CodeFunctionSpec<TInput = unknown, TOutput = unknown> = Omit<
+  CodeFunctionRef<TInput, TOutput>,
+  '$id' | 'kind'
+>
+
+/**
+ * Mint a {@link CodeFunctionRef}. The `handler` may be an inline function or
+ * an `ActionRef` string into `digital-objects`.
+ */
+export function Code<TInput = unknown, TOutput = unknown>(
+  spec: CodeFunctionSpec<TInput, TOutput>
+): CodeFunctionRef<TInput, TOutput> {
+  return {
+    $id: mintId('code', spec.name),
+    kind: 'code',
+    ...spec,
+  }
+}
+
+// ============================================================================
+// Generative
+// ============================================================================
+
+/**
+ * Spec accepted by the {@link Generative} sugar factory.
+ */
+export type GenerativeFunctionSpec = Omit<GenerativeFunctionRef, '$id' | 'kind'>
+
+/**
+ * Mint a {@link GenerativeFunctionRef} — single-shot LLM call.
+ */
+export function Generative(spec: GenerativeFunctionSpec): GenerativeFunctionRef {
+  return {
+    $id: mintId('generative', spec.name),
+    kind: 'generative',
+    ...spec,
+  }
+}
+
+// ============================================================================
+// Agentic
+// ============================================================================
+
+/**
+ * Spec accepted by the {@link Agentic} sugar factory.
+ */
+export type AgenticFunctionSpec = Omit<AgenticFunctionRef, '$id' | 'kind'>
+
+/**
+ * Mint an {@link AgenticFunctionRef} — looping, tool-using AI worker.
+ */
+export function Agentic(spec: AgenticFunctionSpec): AgenticFunctionRef {
+  return {
+    $id: mintId('agentic', spec.name),
+    kind: 'agentic',
+    ...spec,
+  }
+}
+
+// ============================================================================
+// Human
+// ============================================================================
+
+/**
+ * Spec accepted by the {@link Human} sugar factory.
+ */
+export type HumanFunctionSpec = Omit<HumanFunctionRef, '$id' | 'kind'>
+
+/**
+ * Mint a {@link HumanFunctionRef} — work performed by a person, with a
+ * declared rationale and migration policy.
+ */
+export function Human(spec: HumanFunctionSpec): HumanFunctionRef {
+  return {
+    $id: mintId('human', spec.name),
+    kind: 'human',
+    ...spec,
+  }
+}

package/src/index.ts

@@ -12,11 +12,47 @@
  * @packageDocumentation
  */
 
-// Export all types
+// Export all types from types.ts
 export type * from './types.js'
 
-// Re-export AnyTool as a convenience value export
-export type { AnyTool, Tool, ToolCategory, ToolSubcategory, ToolRegistry } from './types.js'
+// Re-export commonly used types explicitly for better discoverability
+// Core types
+export type {
+  Tool,
+  AnyTool,
+  ToolCategory,
+  ToolSubcategory,
+  // Execution types
+  ToolResult,
+  ToolContext,
+  // Configuration types
+  ToolParameter,
+  ToolOutput,
+  ToolPermission,
+  ToolAudience,
+  // Registry types
+  ToolRegistry,
+  ToolQuery,
+  // Builder types
+  DefineToolOptions,
+  // SVO co-design (aip-oejp): verb / frame / auth / pricing / handler ctx
+  Frame,
+  ActionRef,
+  IdentityRef,
+  PaymentRail,
+  PaymentRequired,
+  AuthRequirement,
+  ToolHandlerContext,
+  // id.org.ai canonical types re-exported via types.ts so consumers
+  // don't need a second import. Populated on `ToolHandlerContext` by
+  // `wrapTool()` (aip-lbtr).
+  Identity,
+  PaymentReceipt,
+  // MCP compatibility
+  MCPTool,
+  MCPToolCall,
+  MCPToolResult,
+} from './types.js'
 
 // Export entity type definitions (Nouns for digital tools)
 export {
@@ -72,12 +108,64 @@ export {
 } from './registry.js'
 
 // Export tool definition helpers
+export { defineTool, defineAndRegister, createToolExecutor, toolBuilder } from './define.js'
+
+// Export broker-aware HTTP wrapper (aip-lbtr) — bridges Tool definitions
+// to id.org.ai's AuthBroker + PaymentBroker so paid/auth-gated tools work
+// declaratively without callers manually wiring brokers.
+export { wrapTool } from './wrap.js'
+
+// Export Verb auto-registration helpers (aip-47tm) — explicit, idempotent
+// bridge from `defineTool({ verb, frame })` to `digital-objects`'
+// provider-mediated `defineVerb()`. Callers wire this at startup
+// (`registerToolVerbs`) or lazily per dispatch (`registerToolVerb`).
 export {
-  defineTool,
-  defineAndRegister,
-  createToolExecutor,
-  toolBuilder,
-} from './define.js'
+  registerToolVerb,
+  registerToolVerbs,
+  bootstrapTools,
+  VerbRegistrationConflictError,
+} from './verb-registration.js'
+export type { VerbRegistrationProvider } from './verb-registration.js'
+
+// FunctionRef discriminated union (v3 §6) — the Four Functions promoted to
+// a typed primitive. Additive alongside the legacy `Tool` interface; no
+// existing tools are migrated.
+export type {
+  RewardSignal,
+  PersonaRef,
+  SignOffMode,
+  OversightPolicy,
+  BaseFunctionRef,
+  CodeFunctionRef,
+  GenerativeFunctionRef,
+  AgenticFunctionRef,
+  HumanFunctionRef,
+  HumanRationale,
+  HumanExpirationPolicy,
+  HumanChannel,
+  FunctionRef,
+  FunctionKind,
+} from './function-ref.js'
+
+// Track-record + autonomy ladder primitives (shared with digital-workers
+// once that package re-exports them).
+export type {
+  AgentMode,
+  TrendDirection,
+  TrackRecord,
+  PromotionRule,
+  PromotionPolicy,
+} from './track-record.js'
+
+// Sugar factories — top-level named exports per v3 §6 import style:
+//   import { Code, Generative, Agentic, Human } from 'digital-tools'
+export type {
+  CodeFunctionSpec,
+  GenerativeFunctionSpec,
+  AgenticFunctionSpec,
+  HumanFunctionSpec,
+} from './function-sugar.js'
+export { Code, Generative, Agentic, Human } from './function-sugar.js'
 
 // Export pre-built tools
 export {
@@ -101,6 +189,39 @@ export {
   sendNotification,
   sendSms,
   communicationTools,
+
+  // System tools (fsx.do, gitx.do, bashx.do integration)
+  // Filesystem (fsx.do)
+  fsRead,
+  fsWrite,
+  fsList,
+  fsDelete,
+  fsGlob,
+  fsGrep,
+  fsxTools,
+
+  // Git (gitx.do)
+  gitInit,
+  gitClone,
+  gitStatus,
+  gitAdd,
+  gitCommit,
+  gitLog,
+  gitDiff,
+  gitCheckout,
+  gitPush,
+  gitPull,
+  gitxTools,
+
+  // Bash (bashx.do)
+  bashExec,
+  bashAnalyze,
+  bashScript,
+  bashEnv,
+  bashxTools,
+
+  // All system tools
+  systemTools,
 } from './tools/index.js'
 
 // Export providers (concrete implementations using third-party APIs)
@@ -158,12 +279,13 @@ import { registry } from './registry.js'
 import { webTools } from './tools/web.js'
 import { dataTools } from './tools/data.js'
 import { communicationTools } from './tools/communication.js'
+import { systemTools } from './tools/system.js'
 
 /**
  * Register all built-in tools in the global registry
  */
 export function registerBuiltinTools(): void {
-  for (const tool of [...webTools, ...dataTools, ...communicationTools]) {
+  for (const tool of [...webTools, ...dataTools, ...communicationTools, ...systemTools]) {
     registry.register(tool)
   }
 }
@@ -172,5 +294,5 @@ export function registerBuiltinTools(): void {
  * Get all built-in tools
  */
 export function getBuiltinTools() {
-  return [...webTools, ...dataTools, ...communicationTools]
+  return [...webTools, ...dataTools, ...communicationTools, ...systemTools]
 }

package/src/providers/analytics/mixpanel.ts

@@ -47,8 +47,8 @@ export function createMixpanelProvider(config: ProviderConfig): AnalyticsProvide
     info: mixpanelInfo,
 
     async initialize(cfg: ProviderConfig): Promise<void> {
-      projectToken = cfg.projectToken as string
-      apiSecret = cfg.apiSecret as string | undefined
+      projectToken = cfg['projectToken'] as string
+      apiSecret = cfg['apiSecret'] as string | undefined
 
       if (!projectToken) {
         throw new Error('Mixpanel project token is required')
@@ -76,7 +76,7 @@ export function createMixpanelProvider(config: ProviderConfig): AnalyticsProvide
           body: JSON.stringify([testEvent]),
         })
 
-        const result = await response.json() as { status: number }
+        const result = (await response.json()) as { status: number }
 
         return {
           healthy: response.ok && result.status === 1,
@@ -105,7 +105,9 @@ export function createMixpanelProvider(config: ProviderConfig): AnalyticsProvide
           properties: {
             token: projectToken,
             distinct_id: event.userId || event.anonymousId || 'unknown',
-            time: event.timestamp ? Math.floor(event.timestamp.getTime() / 1000) : Math.floor(Date.now() / 1000),
+            time: event.timestamp
+              ? Math.floor(event.timestamp.getTime() / 1000)
+              : Math.floor(Date.now() / 1000),
             $insert_id: `${event.event}_${Date.now()}_${Math.random().toString(36).substring(7)}`,
             ...event.properties,
           },
@@ -119,7 +121,7 @@ export function createMixpanelProvider(config: ProviderConfig): AnalyticsProvide
           body: JSON.stringify([eventData]),
         })
 
-        const result = await response.json() as { status: number }
+        const result = (await response.json()) as { status: number }
         return response.ok && result.status === 1
       } catch (error) {
         console.error('Mixpanel track error:', error)
@@ -143,7 +145,7 @@ export function createMixpanelProvider(config: ProviderConfig): AnalyticsProvide
           body: JSON.stringify([engageData]),
         })
 
-        const result = await response.json() as { status: number }
+        const result = (await response.json()) as { status: number }
         return response.ok && result.status === 1
       } catch (error) {
         console.error('Mixpanel identify error:', error)
@@ -180,7 +182,7 @@ export function createMixpanelProvider(config: ProviderConfig): AnalyticsProvide
           body: JSON.stringify([aliasEvent]),
         })
 
-        const result = await response.json() as { status: number }
+        const result = (await response.json()) as { status: number }
         return response.ok && result.status === 1
       } catch (error) {
         console.error('Mixpanel alias error:', error)
@@ -205,7 +207,7 @@ export function createMixpanelProvider(config: ProviderConfig): AnalyticsProvide
           return null
         }
 
-        const data = await response.json() as {
+        const data = (await response.json()) as {
           name?: string
           description?: string
           query?: AnalyticsQueryOptions
@@ -216,9 +218,9 @@ export function createMixpanelProvider(config: ProviderConfig): AnalyticsProvide
         return {
           id: reportId,
           name: data.name || reportId,
-          description: data.description,
+          ...(data.description !== undefined && { description: data.description }),
           query: data.query || { metrics: [], dateRange: { start: new Date(), end: new Date() } },
-          result: data.result,
+          ...(data.result !== undefined && { result: data.result }),
           createdAt: data.created ? new Date(data.created) : new Date(),
           updatedAt: data.updated ? new Date(data.updated) : new Date(),
         }
@@ -237,10 +239,11 @@ export function createMixpanelProvider(config: ProviderConfig): AnalyticsProvide
         const auth = Buffer.from(`${apiSecret}:`).toString('base64')
 
         // Construct query parameters
-        const params = new URLSearchParams({
-          from_date: query.dateRange.start.toISOString().split('T')[0],
-          to_date: query.dateRange.end.toISOString().split('T')[0],
-        })
+        const params = new URLSearchParams()
+        const fromDate = query.dateRange.start.toISOString().split('T')[0]
+        const toDate = query.dateRange.end.toISOString().split('T')[0]
+        if (fromDate) params.append('from_date', fromDate)
+        if (toDate) params.append('to_date', toDate)
 
         if (query.metrics.length > 0) {
           params.append('event', query.metrics.join(','))
@@ -251,9 +254,7 @@ export function createMixpanelProvider(config: ProviderConfig): AnalyticsProvide
         }
 
         // Use the segmentation endpoint for queries
-        const endpoint = query.dimensions && query.dimensions.length > 0
-          ? 'segmentation'
-          : 'events'
+        const endpoint = query.dimensions && query.dimensions.length > 0 ? 'segmentation' : 'events'
 
         const response = await fetch(`${MIXPANEL_QUERY_URL}/${endpoint}?${params.toString()}`, {
           headers: {
@@ -265,7 +266,7 @@ export function createMixpanelProvider(config: ProviderConfig): AnalyticsProvide
           throw new Error(`Query failed: ${response.statusText}`)
         }
 
-        const data = await response.json() as {
+        const data = (await response.json()) as {
           data?: Record<string, Record<string, number>>
         }
 

package/src/providers/calendar/cal-com.ts

@@ -30,7 +30,8 @@ const DEFAULT_BASE_URL = 'https://api.cal.com/v1'
 export const calComInfo: ProviderInfo = {
   id: 'calendar.cal-com',
   name: 'Cal.com',
-  description: 'Cal.com API for scheduling and calendar management (open-source Calendly alternative)',
+  description:
+    'Cal.com API for scheduling and calendar management (open-source Calendly alternative)',
   category: 'calendar',
   website: 'https://cal.com',
   docsUrl: 'https://cal.com/docs/api-reference',
@@ -179,7 +180,7 @@ export function createCalComProvider(config: ProviderConfig): CalendarProvider {
         .map((et) => ({
           id: String(et.id),
           name: et.title,
-          description: et.description,
+          ...(et.description !== undefined && { description: et.description }),
           timeZone: 'UTC', // Cal.com handles timezone per user
           primary: et.position === 0,
           accessRole: 'owner' as const,
@@ -204,7 +205,7 @@ export function createCalComProvider(config: ProviderConfig): CalendarProvider {
       return {
         id: String(et.id),
         name: et.title,
-        description: et.description,
+        ...(et.description !== undefined && { description: et.description }),
         timeZone: 'UTC',
         primary: et.position === 0,
         accessRole: 'owner',
@@ -244,15 +245,18 @@ export function createCalComProvider(config: ProviderConfig): CalendarProvider {
         id: booking.uid,
         calendarId,
         summary: booking.title,
-        description: booking.description,
-        location: booking.location,
+        ...(booking.description !== undefined && { description: booking.description }),
+        ...(booking.location !== undefined && { location: booking.location }),
         start: new Date(booking.startTime),
         end: new Date(booking.endTime),
         attendees: booking.attendees.map((a) => ({
           email: a.email,
           responseStatus: booking.status === 'ACCEPTED' ? 'accepted' : 'needsAction',
         })),
-        status: (booking.status === 'CANCELLED' ? 'cancelled' : 'confirmed') as 'confirmed' | 'tentative' | 'cancelled',
+        status: (booking.status === 'CANCELLED' ? 'cancelled' : 'confirmed') as
+          | 'confirmed'
+          | 'tentative'
+          | 'cancelled',
         htmlLink: `${baseUrl.replace('/v1', '')}/booking/${booking.uid}`,
       }
     },
@@ -271,15 +275,18 @@ export function createCalComProvider(config: ProviderConfig): CalendarProvider {
         id: booking.uid,
         calendarId: String(booking.eventTypeId),
         summary: booking.title,
-        description: booking.description,
-        location: booking.location,
+        ...(booking.description !== undefined && { description: booking.description }),
+        ...(booking.location !== undefined && { location: booking.location }),
         start: new Date(booking.startTime),
         end: new Date(booking.endTime),
         attendees: booking.attendees.map((a) => ({
           email: a.email,
           responseStatus: booking.status === 'ACCEPTED' ? 'accepted' : 'needsAction',
         })),
-        status: (booking.status === 'CANCELLED' ? 'cancelled' : 'confirmed') as 'confirmed' | 'tentative' | 'cancelled',
+        status: (booking.status === 'CANCELLED' ? 'cancelled' : 'confirmed') as
+          | 'confirmed'
+          | 'tentative'
+          | 'cancelled',
         htmlLink: `${baseUrl.replace('/v1', '')}/booking/${booking.uid}`,
       }
     },
@@ -321,15 +328,18 @@ export function createCalComProvider(config: ProviderConfig): CalendarProvider {
         id: booking.uid,
         calendarId: String(booking.eventTypeId),
         summary: booking.title,
-        description: booking.description,
-        location: booking.location,
+        ...(booking.description !== undefined && { description: booking.description }),
+        ...(booking.location !== undefined && { location: booking.location }),
         start: new Date(booking.startTime),
         end: new Date(booking.endTime),
         attendees: booking.attendees.map((a) => ({
           email: a.email,
           responseStatus: booking.status === 'ACCEPTED' ? 'accepted' : 'needsAction',
         })),
-        status: (booking.status === 'CANCELLED' ? 'cancelled' : 'confirmed') as 'confirmed' | 'tentative' | 'cancelled',
+        status: (booking.status === 'CANCELLED' ? 'cancelled' : 'confirmed') as
+          | 'confirmed'
+          | 'tentative'
+          | 'cancelled',
         htmlLink: `${baseUrl.replace('/v1', '')}/booking/${booking.uid}`,
       }
     },
@@ -370,15 +380,18 @@ export function createCalComProvider(config: ProviderConfig): CalendarProvider {
         id: booking.uid,
         calendarId: String(booking.eventTypeId),
         summary: booking.title,
-        description: booking.description,
-        location: booking.location,
+        ...(booking.description !== undefined && { description: booking.description }),
+        ...(booking.location !== undefined && { location: booking.location }),
         start: new Date(booking.startTime),
         end: new Date(booking.endTime),
         attendees: booking.attendees.map((a) => ({
           email: a.email,
           responseStatus: booking.status === 'ACCEPTED' ? 'accepted' : 'needsAction',
         })),
-        status: (booking.status === 'CANCELLED' ? 'cancelled' : 'confirmed') as 'confirmed' | 'tentative' | 'cancelled',
+        status: (booking.status === 'CANCELLED' ? 'cancelled' : 'confirmed') as
+          | 'confirmed'
+          | 'tentative'
+          | 'cancelled',
         htmlLink: `${baseUrl.replace('/v1', '')}/booking/${booking.uid}`,
       }))
 
@@ -402,9 +415,7 @@ export function createCalComProvider(config: ProviderConfig): CalendarProvider {
         params.append('dateFrom', timeMin.toISOString())
         params.append('dateTo', timeMax.toISOString())
 
-        const result = await apiRequest<CalComAvailability>(
-          `/availability?${params}`
-        )
+        const result = await apiRequest<CalComAvailability>(`/availability?${params}`)
 
         if (result.ok && result.data) {
           results.push({

package/src/providers/calendar/google-calendar.ts

@@ -85,8 +85,8 @@ export function createGoogleCalendarProvider(config: ProviderConfig): CalendarPr
     info: googleCalendarInfo,
 
     async initialize(cfg: ProviderConfig): Promise<void> {
-      accessToken = cfg.accessToken as string
-      defaultCalendarId = cfg.calendarId as string | undefined
+      accessToken = cfg['accessToken'] as string
+      defaultCalendarId = cfg['calendarId'] as string | undefined
 
       if (!accessToken) {
         throw new Error('Google Calendar access token is required')
@@ -135,7 +135,7 @@ export function createGoogleCalendarProvider(config: ProviderConfig): CalendarPr
       return {
         items,
         hasMore: !!result.data.nextPageToken,
-        nextCursor: result.data.nextPageToken,
+        ...(result.data.nextPageToken !== undefined && { nextCursor: result.data.nextPageToken }),
       }
     },
 
@@ -183,7 +183,8 @@ export function createGoogleCalendarProvider(config: ProviderConfig): CalendarPr
               createRequest: {
                 requestId: `${Date.now()}-${Math.random()}`,
                 conferenceSolutionKey: {
-                  type: event.conferenceData.type === 'hangoutsMeet' ? 'hangoutsMeet' : 'hangoutsMeet',
+                  type:
+                    event.conferenceData.type === 'hangoutsMeet' ? 'hangoutsMeet' : 'hangoutsMeet',
                 },
               },
             }
@@ -191,10 +192,13 @@ export function createGoogleCalendarProvider(config: ProviderConfig): CalendarPr
       }
 
       const params = event.conferenceData ? '?conferenceDataVersion=1' : ''
-      const result = await apiRequest<any>(`/calendars/${encodeURIComponent(calendarId)}/events${params}`, {
-        method: 'POST',
-        body: JSON.stringify(body),
-      })
+      const result = await apiRequest<any>(
+        `/calendars/${encodeURIComponent(calendarId)}/events${params}`,
+        {
+          method: 'POST',
+          body: JSON.stringify(body),
+        }
+      )
 
       if (!result.ok || !result.data) {
         throw new Error(result.error || 'Failed to create event')
@@ -332,7 +336,8 @@ export function createGoogleCalendarProvider(config: ProviderConfig): CalendarPr
       if (options?.cursor) params.append('pageToken', options.cursor)
       if (options?.timeMin) params.append('timeMin', options.timeMin.toISOString())
       if (options?.timeMax) params.append('timeMax', options.timeMax.toISOString())
-      if (options?.singleEvents !== undefined) params.append('singleEvents', String(options.singleEvents))
+      if (options?.singleEvents !== undefined)
+        params.append('singleEvents', String(options.singleEvents))
       if (options?.orderBy) params.append('orderBy', options.orderBy)
 
       const result = await apiRequest<{
@@ -364,7 +369,7 @@ export function createGoogleCalendarProvider(config: ProviderConfig): CalendarPr
       return {
         items,
         hasMore: !!result.data.nextPageToken,
-        nextCursor: result.data.nextPageToken,
+        ...(result.data.nextPageToken !== undefined && { nextCursor: result.data.nextPageToken }),
       }
     },
 
@@ -394,10 +399,11 @@ export function createGoogleCalendarProvider(config: ProviderConfig): CalendarPr
         const calendar = result.data!.calendars[calendarId]
         return {
           calendarId,
-          busy: calendar?.busy?.map((slot) => ({
-            start: new Date(slot.start),
-            end: new Date(slot.end),
-          })) || [],
+          busy:
+            calendar?.busy?.map((slot) => ({
+              start: new Date(slot.start),
+              end: new Date(slot.end),
+            })) || [],
         }
       })
     },