// Copyright 2025 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// https://webmachinelearning.github.io/webmcp/#model-context-container

dictionary ModelContextRegisterToolOptions {
  AbortSignal signal;

  // A list of origins, controlling which document in the frame tree can
  // see/invoke this tool. See
  // https://docs.google.com/document/d/1ycdzuXA-VE8lRDFSArh0Um3PChHV0Hq6Om1MSMG8qPE/edit
  // for more details.
  //
  // In short:
  //   1. When this array is empty or omitted, the tool is only exposed to
  //      documents that are same-origin with the one that registered the tool.
  //   2. When it is provided and non-empty, the tool is exposed to all
  //      documents whose origin matches the one in the list. Additionally, it
  //      is exposed to all same-origin documents, like (1) above.
  sequence<USVString> exposedTo;
};

dictionary ExecuteToolOptions {
  AbortSignal signal;
};

dictionary RegisteredTool {
  required DOMString name;
  required DOMString description;
  DOMString inputSchema;
  // `title` can be exposed as a `DOMString` since it was taken in by a
  // `USVString`, meaning all unmatched surrogate processing has already been
  // done, and there's no need to do it again on tool exposure.
  //
  // This member is always provided when this dictionary is the result of
  // `getTools()`. It is not marked as `required` though, because when used as
  // an input to used to `executeTool()`, it's not necessary for the developer
  // to provide a title. See https://crbug.com/536063275 which should let us
  // stop using this dictionary as an input to `executeTool()`.
  //
  // Also see https://github.com/webmachinelearning/webmcp/issues/224 for
  // discussion about how the browser should expose this member if no title was
  // provided at registration time.
  DOMString title;
  required Window window;
  required USVString origin;
  ToolAnnotations annotations;
};

dictionary ModelContextGetToolOptions {
  // A list of origins, controlling which documents have their tools included
  // in the list
  //
  // In short:
  //   1. When this array is empty or omitted, only tools exposed to
  //      documents that are same-origin with the one calling getTools() are
  //      included in the result.
  //   2. When it is provided and non-empty, tools in documents whose origins
  //      match at least one in the list are included. In addition, same-origin
  //      tools are included as in (1).
  sequence<USVString> fromOrigins;
};

[
    Exposed=Window,
    SecureContext,
    RuntimeEnabled=WebMCP
] interface ModelContext : EventTarget {
  [CallWith=ScriptState, MeasureAs=ModelContextRegisterTool] Promise<undefined> registerTool(ModelContextTool tool, optional ModelContextRegisterToolOptions options = {});
  [CallWith=ScriptState, MeasureAs=ModelContextGetTools] Promise<sequence<RegisteredTool>> getTools(optional ModelContextGetToolOptions options = {});
  [CallWith=ScriptState, MeasureAs=ModelContextExecuteTool] Promise<DOMString?> executeTool(
      RegisteredTool tool,
      DOMString inputArguments,
      optional ExecuteToolOptions options = {}
  );
  attribute EventHandler ontoolchange;
};