Working Context API Reference

Package Overview

The @interopio/working-context package is a TypeScript library that enables developers to build intelligent, context-aware applications by automatically collecting and managing contextual information from multiple data sources within io.Connect. The package provides a schema-driven approach to tracking and exposing contextual data, making it readily available for AI agents, LLMs, or application logic.

What is Working Context?

Working Context represents the current state and information relevant to a user's workflow. This package automatically tracks, updates, and exposes contextual data from various sources within your application, including global contexts, workspaces, channels, and application instances. By defining a schema that describes your data sources, the package handles all the complexity of context collection and management.

Key Features

• Automatic Context Collection: Define schemas describing your data sources, and the package handles the rest
• Multiple Source Support: Track data from global contexts, workspaces, channels, and application instances
• Type-Safe with TypeScript: Built with TypeScript for complete type safety and IntelliSense support
• Reactive Updates: Subscribe to context changes and respond to updates in real-time
• Flexible Integration: Works standalone or integrates with other io.Intelligence packages

Used Across the io.Intelligence Stack

Working Context is also used as a building block for:

• AI Web, where context can be injected into assistant flows
• io.Assist NG, where context supports the embedded Angular assistant
• MCP Core, where it powers the working-context system tool
• MCP HTTP, where it can be exposed through the HTTP transport
• MCP Web, where it can be exposed through the web transport

If you are deciding where Working Context fits in the overall product, start with the Introduction and then follow the package path that matches your integration.

Installation

Install the package using npm:

npm install @interopio/working-context

Factory Function

IoIntelWorkingContextFactory

The main entry point for creating a Working Context instance.

Signature:

IoIntelWorkingContextFactory(
    io: IOConnectBrowser.API,
    config: IoIntelWorkingContext.Config
): Promise<IoIntelWorkingContext.API>

Parameters:

Parameter	Type	Required	Description
io	IOConnectBrowser.API	Yes	The io.Connect browser API instance. Providing an io.Connect API with Workspaces API configured is required for all Workspaces tracking.
config	IoIntelWorkingContext.Config	Yes	Configuration object defining the schema and sources to track

Returns:

• Promise<IoIntelWorkingContext.API> - A Promise that resolves to the Working Context API

Example:

import { IoIntelWorkingContextFactory } from "@interopio/working-context";

const workingContext = await IoIntelWorkingContextFactory(io, {
  schema: {
    userName: {
      type: "string",
      description: "Current user's full name",
      source: {
        context: {
          location: {
            global: { names: ["UserProfile"] },
          },
          path: "user.name",
        },
      },
    },
  },
});

Working Context API

Once initialized, the Working Context API provides two main methods for accessing and monitoring context data.

get()

Retrieves the current state of all tracked properties.

Signature:

get(): Record<string, Property>

Returns:

• Record<string, Property> - Object containing all tracked properties with their current values

Property Interface:

interface Property {
  description?: string;
  value: any;
}

Property	Type	Required	Description
description	string	No	Optional description of the property
value	any	Yes	The current value of the property

Example:

const currentContext = workingContext.get();
console.log(currentContext.userName.value); // "John Doe"
console.log(currentContext.userName.description); // "Current user's full name"

onChanged()

Subscribes to context changes and receives updates whenever tracked context data changes.

Signature:

onChanged(
    callback: (data: Record<string, Property>) => void
): UnsubscribeFunction

Parameters:

Parameter	Type	Required	Description
callback	(data: Record<string, Property>) => void	Yes	Function called whenever context changes. Receives the updated context as an argument.

Returns:

• UnsubscribeFunction - Function to call to stop receiving updates

Example:

const unsubscribe = workingContext.onChanged((updatedContext) => {
  console.log("Context updated:", updatedContext);

  // Access specific properties
  if (updatedContext.userName) {
    console.log("User name changed to:", updatedContext.userName.value);
  }
});

// Later, to stop listening to updates:
unsubscribe();